@pragmatic-growth/memory-mcp 2.1.1 → 2.3.0

package/.npmrc.backup

@@ -0,0 +1,2 @@
+@pragmatic-growth:registry=https://registry.npmjs.org/
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}

package/README.md

@@ -41,14 +41,11 @@ For clients that only support stdio (Raycast, local tools):
 Both transports support two operating modes:
 
 ### Read-Only Mode (Default)
-Safe for general use - only search and read operations:
-- `search_knowledge` - Semantic search with relevance scores
-- `answer_question` - RAG with auto-generation
-- `get_article` - Get article by ID
-- `list_articles` - Browse articles with category filter
-- `list_categories` - List categories with article counts
-- `log_unanswered` - Flag knowledge gaps
-- `health_check` - System status
+Safe for general use - search, read, and conversation tracking:
+- **Core Knowledge**: search, get content, answer questions, list content
+- **Knowledge Graph**: find related articles, get entities, search entities
+- **Episodic Memory**: start/track conversations, get session context
+- **Q&A**: add questions for later answering
 
 ### Full Mode (with `--full` flag)
 Includes all read-only tools PLUS write operations:
@@ -113,28 +110,53 @@ MCP_API_KEY=your-key memory-mcp --full
 
 Note: The `--full` CLI flag takes precedence over `MCP_MODE` env var.
 
-## Available Tools
+## Available Tools (21 Total)
 
-### Core Tools (All Modes)
+### Core Knowledge Tools (7)
 
 | Tool | Description |
 |------|-------------|
-| `search_knowledge` | Semantic search with relevance scores |
-| `answer_question` | Full RAG pipeline with auto-generation |
-| `get_article` | Retrieve complete article by ID |
-| `list_articles` | Browse articles with optional category filter |
-| `list_categories` | List all categories with article counts |
+| `search_knowledge` | Semantic search across articles AND Q&A entries |
+| `get_content` | Retrieve full content by ID (articles or Q&A) |
+| `answer_question` | Full RAG pipeline with graph-augmented retrieval |
 | `log_unanswered` | Flag questions for knowledge gap analysis |
+| `list_content` | Browse articles and Q&A with filtering |
+| `list_categories` | List all categories with content counts |
 | `health_check` | Check system status and connectivity |
 
-### Full Mode Tools
+### Knowledge Graph Tools (4)
 
 | Tool | Description |
 |------|-------------|
-| `add_article` | Create a new article with automatic embedding generation |
+| `find_related` | Find related articles via shared entities |
+| `get_entities` | Get named entities from an article |
+| `search_entities` | Search entities by name or type |
+| `get_knowledge_graph` | Get graph structure for visualization |
+
+### Episodic Memory Tools (5)
+
+| Tool | Description |
+|------|-------------|
+| `start_conversation` | Begin tracking a conversation session |
+| `add_message` | Add message with automatic fact extraction |
+| `get_conversation` | Retrieve conversation with all messages |
+| `list_conversations` | List recent conversations |
+| `get_session_context` | Get context for follow-up questions |
+
+### Q&A Tools (1)
+
+| Tool | Description |
+|------|-------------|
+| `add_question` | Add question for later expert answering |
+
+### Full Mode Tools (4)
+
+| Tool | Description |
+|------|-------------|
+| `add_article` | Create a new article with automatic embedding |
 | `edit_article` | Update article content, metadata, or category |
-| `remove_article` | Soft-delete an article (preserves data for audit) |
-| `rate_answer` | Rate previous answers: -1 (unhelpful), 0 (neutral), 1 (helpful) |
+| `remove_article` | Soft-delete an article |
+| `rate_answer` | Rate previous answers: -1, 0, or 1 |
 
 ## MCP Resources
 
@@ -167,6 +189,18 @@ For full mode to work:
 1. The stdio proxy must have `--full` flag OR `MCP_MODE=full`
 2. The remote server must have `MCP_MODE=full` in its environment
 
+## Changelog
+
+### v2.2.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 2025-11-25
+
+### v2.1.1
+- Initial public release with core knowledge tools
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -11,8 +11,12 @@
  *   npx @pragmatic-growth/memory-mcp --edit      # Alias for --full
  *
  * Environment variables:
- *   MCP_API_KEY - API key for authentication (required)
+ *   MCP_API_KEY - Clerk API key for authentication (required)
  *   MCP_SERVER_URL - Server URL (default: https://pg-memory-production.up.railway.app/api/mcp)
  *   MCP_MODE - Mode: 'readonly' (default) or 'full' for edit capabilities
+ *
+ * Authentication:
+ *   Uses Clerk API key authentication via X-API-Key header.
+ *   Get your API key from the Clerk Dashboard or the app's API Docs page.
  */
 export {};

package/dist/index.js

@@ -11,9 +11,13 @@
  *   npx @pragmatic-growth/memory-mcp --edit      # Alias for --full
  *
  * Environment variables:
- *   MCP_API_KEY - API key for authentication (required)
+ *   MCP_API_KEY - Clerk API key for authentication (required)
  *   MCP_SERVER_URL - Server URL (default: https://pg-memory-production.up.railway.app/api/mcp)
  *   MCP_MODE - Mode: 'readonly' (default) or 'full' for edit capabilities
+ *
+ * Authentication:
+ *   Uses Clerk API key authentication via X-API-Key header.
+ *   Get your API key from the Clerk Dashboard or the app's API Docs page.
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -28,18 +32,20 @@ const SERVER_URL = process.env.MCP_SERVER_URL || 'https://pg-memory-production.u
 const API_KEY = process.env.MCP_API_KEY;
 if (!API_KEY) {
     console.error('Error: MCP_API_KEY environment variable is required');
-    console.error('Set it in your Raycast MCP server configuration under "env"');
+    console.error('Get your Clerk API key from the Clerk Dashboard or app API Docs page');
+    console.error('Set it in your MCP client configuration under "env"');
     process.exit(1);
 }
 // HTTP session management
 let sessionId = null;
 /**
  * Make an HTTP request to the remote MCP server.
+ * Uses X-API-Key header for Clerk API key authentication.
  */
 async function callRemoteServer(method, params) {
     const headers = {
         'Content-Type': 'application/json',
-        'Authorization': `Bearer ${API_KEY}`,
+        'X-API-Key': API_KEY, // Safe: already validated above
     };
     if (sessionId) {
         headers['Mcp-Session-Id'] = sessionId;
@@ -75,7 +81,7 @@ async function initializeRemoteSession() {
         capabilities: {},
         clientInfo: {
             name: 'pg-memory-stdio',
-            version: '2.1.0',
+            version: '2.3.0',
         },
     });
 }
@@ -95,28 +101,30 @@ async function main() {
     // Create local MCP server
     const server = new McpServer({
         name: 'pg-memory',
-        version: '2.1.0',
+        version: '2.3.0',
         description: `PG-Memory knowledge base (${modeLabel} mode)`,
     });
     // ============================================================
-    // READ-ONLY TOOLS (available in all modes)
+    // CORE KNOWLEDGE TOOLS (available in all modes)
     // ============================================================
-    // Tool 1: Search Knowledge (matches HTTP server's search_knowledge)
+    // Tool 1: Search Knowledge (Articles + Q&A)
     server.tool('search_knowledge', `Search the nonresident.tax knowledge base using semantic similarity.
 
-This knowledge base contains comprehensive information about:
-- Services: LLC formation, tax filing, registered agent, accounting
-- Pricing: Package costs, annual fees, consultation fees
+**YOU MUST CALL THIS TOOL** before answering any domain-specific question.
+
+Topics covered:
 - Tax compliance: Form 5472, Form 1120, ECI rules, penalties, deadlines
 - Company formation: Wyoming LLC, Delaware LLC, single-member LLC
 - Banking: Mercury, Wise, US bank account requirements
-- Process: Onboarding steps, document requirements, timelines
-- Dissolution: LLC closure, final filings, IRS compliance
+- Services & pricing: LLC formation, tax filing, registered agent
 
-Returns relevant articles with relevance scores. Use get_article to retrieve full content.`, {
+Returns relevant articles AND Q&A entries with relevance scores.
+Use get_content with the ID to retrieve full content.`, {
         query: z.string().describe('The question or topic to search for'),
-        limit: z.number().optional().describe('Maximum number of results to return (default: 5)'),
-        threshold: z.number().optional().describe('Minimum similarity threshold 0-1 (default: 0.55)'),
+        limit: z.number().optional().describe('Maximum results to return (default: 5)'),
+        threshold: z.number().optional().describe('Minimum similarity 0-1 (default: 0.55)'),
+        include_articles: z.boolean().optional().describe('Include articles (default: true)'),
+        include_qa: z.boolean().optional().describe('Include Q&A entries (default: true)'),
     }, async (args) => {
         const result = await callRemoteServer('tools/call', {
             name: 'search_knowledge',
@@ -124,44 +132,38 @@ Returns relevant articles with relevance scores. Use get_article to retrieve ful
         });
         return result;
     });
-    // Tool 2: Get Article
-    server.tool('get_article', `Retrieve the complete content of a knowledge base article by ID.
+    // Tool 2: Get Content (Unified - Articles + Q&A)
+    server.tool('get_content', `Retrieve complete content from the knowledge base by ID.
 
-Use this tool when:
-- You have an article ID from search_knowledge or list_articles
-- You need the full article content (not just summary)
-- You want to verify specific details from search results
+Automatically detects content type from ID prefix:
+- 'art_*' → Article (knowledge base article)
+- 'qa_*' → Q&A entry (question and answer)
 
-Returns: Full article with title, content, summary, category, tags, version, and last update date.`, {
-        article_id: z.string().describe('The article ID (e.g., art_abc123)'),
+Use summary_only=true first to check content size, then fetch with max_length if needed.`, {
+        content_id: z.string().describe('Content ID (e.g., art_abc123 or qa_xyz789)'),
+        max_length: z.number().optional().describe('Max content length in chars (truncates if exceeded)'),
+        summary_only: z.boolean().optional().describe('Return only summary/metadata (default: false)'),
     }, async (args) => {
         const result = await callRemoteServer('tools/call', {
-            name: 'get_article',
+            name: 'get_content',
             arguments: args,
         });
         return result;
     });
     // Tool 3: Answer Question (Full RAG)
-    server.tool('answer_question', `Answer a customer question using the knowledge base with full RAG.
-
-This tool:
-1. Searches for relevant articles in the knowledge base
-2. If found: Generates an answer synthesizing the retrieved content
-3. If not found: Optionally generates a new article to fill the gap
+    server.tool('answer_question', `Answer a customer question using the knowledge base with full RAG pipeline.
 
-Use for questions about:
-- Services and pricing
-- Tax filing requirements and deadlines
-- LLC formation process
-- Bank account options
-- Document requirements
-- How onboarding works
-- Any nonresident.tax topic
+How it works:
+1. Searches for relevant articles AND published Q&A
+2. Uses knowledge graph to find related content via entities
+3. Generates a synthesized answer from all sources
+4. Returns source references for transparency
 
-The answer includes source references for transparency.`, {
+Use this when you need a complete answer with sources, not just search results.`, {
         question: z.string().describe('The customer question to answer'),
-        context: z.string().optional().describe('Additional context about the question'),
-        generate_if_not_found: z.boolean().optional().describe('Generate new article if no relevant content found (default: true)'),
+        context: z.string().optional().describe('Additional context'),
+        generate_if_not_found: z.boolean().optional().describe('Generate new article if not found (default: true)'),
+        use_graph: z.boolean().optional().describe('Enable graph-augmented retrieval (default: true)'),
     }, async (args) => {
         const result = await callRemoteServer('tools/call', {
             name: 'answer_question',
@@ -172,19 +174,10 @@ The answer includes source references for transparency.`, {
     // Tool 4: Log Unanswered
     server.tool('log_unanswered', `Flag a customer question as unanswered for knowledge gap analysis.
 
-WHEN TO USE:
-- After search_knowledge returns no relevant results
-- When existing articles don't fully answer the question
-- When a customer asks something completely new
-- To track recurring questions that need dedicated articles
-
-WHY IT MATTERS:
-- Flagged questions appear in the admin "Knowledge Gaps" section
-- Helps prioritize which new articles to create
-- Builds a list of topics customers actually need
-- Improves the knowledge base over time`, {
+**CALL THIS** when search_knowledge returns no results or low confidence.
+Flagged questions appear in admin "Knowledge Gaps" section.`, {
         query: z.string().describe('The question that could not be answered'),
-        reason: z.string().optional().describe('Reason why the question could not be answered'),
+        reason: z.string().optional().describe('Reason why'),
     }, async (args) => {
         const result = await callRemoteServer('tools/call', {
             name: 'log_unanswered',
@@ -192,31 +185,24 @@ WHY IT MATTERS:
         });
         return result;
     });
-    // Tool 5: List Articles
-    server.tool('list_articles', `Browse articles in the knowledge base with optional filtering.
-
-Parameters:
-- limit: Number of articles (default 10, max 50)
-- category: Filter by category slug (use list_categories first)
+    // Tool 5: List Content (Unified - Articles + Q&A)
+    server.tool('list_content', `Browse content in the knowledge base with optional filtering.
 
-Returns article ID, title, and summary for each match.
-Use get_article with the ID to retrieve full content.
-
-WORKFLOW:
-1. Call list_categories to discover available categories
-2. Call list_articles with specific category for focused results
-3. Call get_article for articles that look relevant`, {
-        limit: z.number().optional().describe('Number of articles to return (max 50)'),
+Supports: articles, qa, or all (default).
+Use list_categories first to discover available categories.`, {
+        type: z.enum(['articles', 'qa', 'all']).optional().describe('Content type (default: all)'),
+        limit: z.number().optional().describe('Number of items (default: 10, max: 50)'),
         category: z.string().optional().describe('Filter by category slug'),
+        status: z.string().optional().describe('Filter Q&A by status: pending, draft, published'),
     }, async (args) => {
         const result = await callRemoteServer('tools/call', {
-            name: 'list_articles',
+            name: 'list_content',
             arguments: args,
         });
         return result;
     });
     // Tool 6: Health Check
-    server.tool('health_check', 'Check the health status of the memory system.', {}, async () => {
+    server.tool('health_check', 'Check the health status of the memory system including article/Q&A counts.', {}, async () => {
         const result = await callRemoteServer('tools/call', {
             name: 'health_check',
             arguments: {},
@@ -224,22 +210,8 @@ WORKFLOW:
         return result;
     });
     // Tool 7: List Categories
-    server.tool('list_categories', `List all categories in the knowledge base with article counts.
-
-CRITICAL FOR EFFICIENT SEARCH:
-Categories help you quickly narrow down to relevant content.
-
-Returns for each category:
-- slug: Category identifier for filtering
-- name: Human-readable name
-- count: Number of articles
-- description: What the category covers
-
-RECOMMENDED WORKFLOW:
-1. Call list_categories to see what's available
-2. Call list_articles with category slug
-3. Call get_article for full content
-4. Or use search_knowledge for semantic search across all`, {}, async () => {
+    server.tool('list_categories', `List all categories in the knowledge base with content counts.
+Use category slugs with list_content for filtered browsing.`, {}, async () => {
         const result = await callRemoteServer('tools/call', {
             name: 'list_categories',
             arguments: {},
@@ -247,17 +219,152 @@ RECOMMENDED WORKFLOW:
         return result;
     });
     // ============================================================
-    // FULL MODE TOOLS (only available with --full flag or MCP_MODE=full)
+    // KNOWLEDGE GRAPH TOOLS (available in all modes)
+    // ============================================================
+    // Tool 8: Find Related Articles
+    server.tool('find_related', 'Find articles related through shared entities or explicit relationships. Uses graph traversal.', {
+        article_id: z.string().describe('Article ID to find relations for'),
+        max_depth: z.number().optional().describe('Relationship hops 1-5 (default: 2)'),
+        min_strength: z.number().optional().describe('Min strength 0-1 (default: 0.3)'),
+        limit: z.number().optional().describe('Max articles (default: 10)'),
+    }, async (args) => {
+        const result = await callRemoteServer('tools/call', {
+            name: 'find_related',
+            arguments: args,
+        });
+        return result;
+    });
+    // Tool 9: Get Entities
+    server.tool('get_entities', 'Get named entities from an article (people, orgs, forms, states, etc.).', {
+        article_id: z.string().describe('Article ID to get entities for'),
+    }, async (args) => {
+        const result = await callRemoteServer('tools/call', {
+            name: 'get_entities',
+            arguments: args,
+        });
+        return result;
+    });
+    // Tool 10: Search Entities
+    server.tool('search_entities', 'Search for entities by name or type across the knowledge base.', {
+        query: z.string().optional().describe('Search query for entity name'),
+        type: z.string().optional().describe('Filter: PERSON, ORGANIZATION, FORM, STATE, COUNTRY, DATE, AMOUNT, CONCEPT, REGULATION, SERVICE, DOCUMENT'),
+        limit: z.number().optional().describe('Max entities (default: 20)'),
+    }, async (args) => {
+        const result = await callRemoteServer('tools/call', {
+            name: 'search_entities',
+            arguments: args,
+        });
+        return result;
+    });
+    // Tool 11: Get Knowledge Graph
+    server.tool('get_knowledge_graph', 'Get the knowledge graph structure for visualization. Returns nodes and edges.', {
+        center_article_id: z.string().optional().describe('Center on this article'),
+        depth: z.number().optional().describe('Traversal depth 1-5 (default: 2)'),
+        include_entities: z.boolean().optional().describe('Include entity nodes (default: true)'),
+        include_metadata: z.boolean().optional().describe('Include full metadata (default: false)'),
+        limit: z.number().optional().describe('Max nodes (default: 20, max: 100)'),
+    }, async (args) => {
+        const result = await callRemoteServer('tools/call', {
+            name: 'get_knowledge_graph',
+            arguments: args,
+        });
+        return result;
+    });
+    // ============================================================
+    // EPISODIC MEMORY TOOLS (available in all modes)
+    // ============================================================
+    // Tool 12: Start Conversation
+    server.tool('start_conversation', `Start a new conversation for tracking episodic memory.
+Call at the beginning of each session to enable context continuity.`, {
+        session_id: z.string().describe('Session ID (e.g., MCP session ID)'),
+        title: z.string().optional().describe('Conversation title'),
+        user_id: z.string().optional().describe('User ID for multi-user tracking'),
+    }, async (args) => {
+        const result = await callRemoteServer('tools/call', {
+            name: 'start_conversation',
+            arguments: args,
+        });
+        return result;
+    });
+    // Tool 13: Add Message
+    server.tool('add_message', `Add a message to an existing conversation.
+Call after each user message and assistant response.
+User facts are automatically extracted.`, {
+        conversation_id: z.string().describe('Conversation ID from start_conversation'),
+        role: z.enum(['user', 'assistant', 'system']).describe('Message role'),
+        content: z.string().describe('Message content'),
+        referenced_articles: z.string().optional().describe('Comma-separated article IDs referenced'),
+    }, async (args) => {
+        const result = await callRemoteServer('tools/call', {
+            name: 'add_message',
+            arguments: args,
+        });
+        return result;
+    });
+    // Tool 14: Get Conversation
+    server.tool('get_conversation', 'Retrieve a conversation with all its messages by ID.', {
+        conversation_id: z.string().describe('Conversation ID'),
+    }, async (args) => {
+        const result = await callRemoteServer('tools/call', {
+            name: 'get_conversation',
+            arguments: args,
+        });
+        return result;
+    });
+    // Tool 15: List Conversations
+    server.tool('list_conversations', 'List conversations for a session or user. Returns recent first.', {
+        session_id: z.string().optional().describe('Filter by session ID'),
+        user_id: z.string().optional().describe('Filter by user ID'),
+        limit: z.number().optional().describe('Max conversations (default: 20)'),
+    }, async (args) => {
+        const result = await callRemoteServer('tools/call', {
+            name: 'list_conversations',
+            arguments: args,
+        });
+        return result;
+    });
+    // Tool 16: Get Session Context
+    server.tool('get_session_context', `Get recent conversation context for a session.
+Call when user refers to prior conversation or asks follow-up questions.`, {
+        session_id: z.string().describe('Session ID to get context for'),
+        message_limit: z.number().optional().describe('Max messages (default: 10)'),
+    }, async (args) => {
+        const result = await callRemoteServer('tools/call', {
+            name: 'get_session_context',
+            arguments: args,
+        });
+        return result;
+    });
+    // ============================================================
+    // Q&A TOOLS (available in all modes)
+    // ============================================================
+    // Tool 17: Add Question
+    server.tool('add_question', `Add a new question to the Q&A store for later answering.
+Use to capture questions from external channels.`, {
+        question: z.string().describe('The question text'),
+        category: z.string().optional().describe('Category slug'),
+        tags: z.string().optional().describe('Comma-separated tags'),
+        priority: z.string().optional().describe('Priority: low, medium, high, critical'),
+        source: z.string().optional().describe('Source: mcp, email, manual, import'),
+    }, async (args) => {
+        const result = await callRemoteServer('tools/call', {
+            name: 'add_question',
+            arguments: args,
+        });
+        return result;
+    });
+    // ============================================================
+    // FULL MODE TOOLS (only with --full flag or MCP_MODE=full)
     // ============================================================
     if (isFullMode) {
-        // Tool 8: Add Article
-        server.tool('add_article', 'Create a new article in the knowledge base. Automatically generates embedding for semantic search.', {
+        // Tool 18: Add Article
+        server.tool('add_article', 'Create a new article in the knowledge base. Generates embedding automatically.', {
             title: z.string().describe('Article title'),
-            content: z.string().describe('Article content in markdown format'),
-            summary: z.string().optional().describe('Brief summary (auto-generated if not provided)'),
-            category: z.string().optional().describe('Category (e.g., federal-tax, state-compliance)'),
+            content: z.string().describe('Article content in markdown'),
+            summary: z.string().optional().describe('Brief summary (auto-generated if omitted)'),
+            category: z.string().optional().describe('Category slug'),
             tags: z.string().optional().describe('Comma-separated tags'),
-            source: z.string().optional().describe('Source of the article (e.g., manual, irs.gov)'),
+            source: z.string().optional().describe('Source (e.g., manual, irs.gov)'),
         }, async (args) => {
             const result = await callRemoteServer('tools/call', {
                 name: 'add_article',
@@ -265,7 +372,7 @@ RECOMMENDED WORKFLOW:
             });
             return result;
         });
-        // Tool 9: Edit Article
+        // Tool 19: Edit Article
         server.tool('edit_article', 'Update an existing article. Re-generates embedding if content changes.', {
             article_id: z.string().describe('Article ID to update'),
             title: z.string().optional().describe('New title'),
@@ -280,10 +387,10 @@ RECOMMENDED WORKFLOW:
             });
             return result;
         });
-        // Tool 10: Remove Article
-        server.tool('remove_article', 'Soft-delete an article from the knowledge base. Article is marked as deleted but not permanently removed.', {
+        // Tool 20: Remove Article
+        server.tool('remove_article', 'Soft-delete an article. Marked as deleted but not permanently removed.', {
             article_id: z.string().describe('Article ID to remove'),
-            reason: z.string().optional().describe('Reason for deletion (for audit log)'),
+            reason: z.string().optional().describe('Reason for deletion'),
         }, async (args) => {
             const result = await callRemoteServer('tools/call', {
                 name: 'remove_article',
@@ -291,11 +398,11 @@ RECOMMENDED WORKFLOW:
             });
             return result;
         });
-        // Tool 11: Rate Answer
-        server.tool('rate_answer', 'Rate a previous answer as helpful, unhelpful, or neutral. Helps improve the knowledge base.', {
-            query_id: z.string().describe('Query log ID from a previous answer_question response'),
+        // Tool 21: Rate Answer
+        server.tool('rate_answer', 'Rate a previous answer as helpful, unhelpful, or neutral.', {
+            query_id: z.string().describe('Query log ID from answer_question'),
             rating: z.number().describe('Rating: -1 (unhelpful), 0 (neutral), 1 (helpful)'),
-            feedback: z.string().optional().describe('Optional text feedback'),
+            feedback: z.string().optional().describe('Optional feedback text'),
         }, async (args) => {
             const result = await callRemoteServer('tools/call', {
                 name: 'rate_answer',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pragmatic-growth/memory-mcp",
-  "version": "2.1.1",
-  "description": "Stdio proxy for PG-Memory - connects stdio-based MCP clients (Raycast, local tools) to your PG-Memory HTTP server. PG-Memory supports both HTTP transport (Claude Code, mcp-remote) and stdio transport (this package).",
+  "version": "2.3.0",
+  "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. Supports both read-only and full edit modes.",
   "main": "dist/index.js",
   "bin": {
     "memory-mcp": "./dist/index.js"

package/src/index.ts

@@ -11,9 +11,13 @@
  *   npx @pragmatic-growth/memory-mcp --edit      # Alias for --full
  *
  * Environment variables:
- *   MCP_API_KEY - API key for authentication (required)
+ *   MCP_API_KEY - Clerk API key for authentication (required)
  *   MCP_SERVER_URL - Server URL (default: https://pg-memory-production.up.railway.app/api/mcp)
  *   MCP_MODE - Mode: 'readonly' (default) or 'full' for edit capabilities
+ *
+ * Authentication:
+ *   Uses Clerk API key authentication via X-API-Key header.
+ *   Get your API key from the Clerk Dashboard or the app's API Docs page.
  */
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
@@ -32,7 +36,8 @@ const API_KEY = process.env.MCP_API_KEY;
 
 if (!API_KEY) {
   console.error('Error: MCP_API_KEY environment variable is required');
-  console.error('Set it in your Raycast MCP server configuration under "env"');
+  console.error('Get your Clerk API key from the Clerk Dashboard or app API Docs page');
+  console.error('Set it in your MCP client configuration under "env"');
   process.exit(1);
 }
 
@@ -49,11 +54,12 @@ interface JsonRpcResponse {
 
 /**
  * Make an HTTP request to the remote MCP server.
+ * Uses X-API-Key header for Clerk API key authentication.
  */
 async function callRemoteServer(method: string, params?: Record<string, unknown>): Promise<unknown> {
   const headers: Record<string, string> = {
     'Content-Type': 'application/json',
-    'Authorization': `Bearer ${API_KEY}`,
+    'X-API-Key': API_KEY!, // Safe: already validated above
   };
 
   if (sessionId) {
@@ -97,7 +103,7 @@ async function initializeRemoteSession(): Promise<void> {
     capabilities: {},
     clientInfo: {
       name: 'pg-memory-stdio',
-      version: '2.1.0',
+      version: '2.3.0',
     },
   });
 }
@@ -119,33 +125,35 @@ async function main(): Promise<void> {
   // Create local MCP server
   const server = new McpServer({
     name: 'pg-memory',
-    version: '2.1.0',
+    version: '2.3.0',
     description: `PG-Memory knowledge base (${modeLabel} mode)`,
   });
 
   // ============================================================
-  // READ-ONLY TOOLS (available in all modes)
+  // CORE KNOWLEDGE TOOLS (available in all modes)
   // ============================================================
 
-  // Tool 1: Search Knowledge (matches HTTP server's search_knowledge)
+  // Tool 1: Search Knowledge (Articles + Q&A)
   server.tool(
     'search_knowledge',
     `Search the nonresident.tax knowledge base using semantic similarity.
 
-This knowledge base contains comprehensive information about:
-- Services: LLC formation, tax filing, registered agent, accounting
-- Pricing: Package costs, annual fees, consultation fees
+**YOU MUST CALL THIS TOOL** before answering any domain-specific question.
+
+Topics covered:
 - Tax compliance: Form 5472, Form 1120, ECI rules, penalties, deadlines
 - Company formation: Wyoming LLC, Delaware LLC, single-member LLC
 - Banking: Mercury, Wise, US bank account requirements
-- Process: Onboarding steps, document requirements, timelines
-- Dissolution: LLC closure, final filings, IRS compliance
+- Services & pricing: LLC formation, tax filing, registered agent
 
-Returns relevant articles with relevance scores. Use get_article to retrieve full content.`,
+Returns relevant articles AND Q&A entries with relevance scores.
+Use get_content with the ID to retrieve full content.`,
     {
       query: z.string().describe('The question or topic to search for'),
-      limit: z.number().optional().describe('Maximum number of results to return (default: 5)'),
-      threshold: z.number().optional().describe('Minimum similarity threshold 0-1 (default: 0.55)'),
+      limit: z.number().optional().describe('Maximum results to return (default: 5)'),
+      threshold: z.number().optional().describe('Minimum similarity 0-1 (default: 0.55)'),
+      include_articles: z.boolean().optional().describe('Include articles (default: true)'),
+      include_qa: z.boolean().optional().describe('Include Q&A entries (default: true)'),
     },
     async (args) => {
       const result = await callRemoteServer('tools/call', {
@@ -156,23 +164,24 @@ Returns relevant articles with relevance scores. Use get_article to retrieve ful
     }
   );
 
-  // Tool 2: Get Article
+  // Tool 2: Get Content (Unified - Articles + Q&A)
   server.tool(
-    'get_article',
-    `Retrieve the complete content of a knowledge base article by ID.
+    'get_content',
+    `Retrieve complete content from the knowledge base by ID.
 
-Use this tool when:
-- You have an article ID from search_knowledge or list_articles
-- You need the full article content (not just summary)
-- You want to verify specific details from search results
+Automatically detects content type from ID prefix:
+- 'art_*' → Article (knowledge base article)
+- 'qa_*' → Q&A entry (question and answer)
 
-Returns: Full article with title, content, summary, category, tags, version, and last update date.`,
+Use summary_only=true first to check content size, then fetch with max_length if needed.`,
     {
-      article_id: z.string().describe('The article ID (e.g., art_abc123)'),
+      content_id: z.string().describe('Content ID (e.g., art_abc123 or qa_xyz789)'),
+      max_length: z.number().optional().describe('Max content length in chars (truncates if exceeded)'),
+      summary_only: z.boolean().optional().describe('Return only summary/metadata (default: false)'),
     },
     async (args) => {
       const result = await callRemoteServer('tools/call', {
-        name: 'get_article',
+        name: 'get_content',
         arguments: args,
       }) as { content: Array<{ type: 'text'; text: string }> };
       return result;
@@ -182,27 +191,20 @@ Returns: Full article with title, content, summary, category, tags, version, and
   // Tool 3: Answer Question (Full RAG)
   server.tool(
     'answer_question',
-    `Answer a customer question using the knowledge base with full RAG.
-
-This tool:
-1. Searches for relevant articles in the knowledge base
-2. If found: Generates an answer synthesizing the retrieved content
-3. If not found: Optionally generates a new article to fill the gap
-
-Use for questions about:
-- Services and pricing
-- Tax filing requirements and deadlines
-- LLC formation process
-- Bank account options
-- Document requirements
-- How onboarding works
-- Any nonresident.tax topic
-
-The answer includes source references for transparency.`,
+    `Answer a customer question using the knowledge base with full RAG pipeline.
+
+How it works:
+1. Searches for relevant articles AND published Q&A
+2. Uses knowledge graph to find related content via entities
+3. Generates a synthesized answer from all sources
+4. Returns source references for transparency
+
+Use this when you need a complete answer with sources, not just search results.`,
     {
       question: z.string().describe('The customer question to answer'),
-      context: z.string().optional().describe('Additional context about the question'),
-      generate_if_not_found: z.boolean().optional().describe('Generate new article if no relevant content found (default: true)'),
+      context: z.string().optional().describe('Additional context'),
+      generate_if_not_found: z.boolean().optional().describe('Generate new article if not found (default: true)'),
+      use_graph: z.boolean().optional().describe('Enable graph-augmented retrieval (default: true)'),
     },
     async (args) => {
       const result = await callRemoteServer('tools/call', {
@@ -218,20 +220,11 @@ The answer includes source references for transparency.`,
     'log_unanswered',
     `Flag a customer question as unanswered for knowledge gap analysis.
 
-WHEN TO USE:
-- After search_knowledge returns no relevant results
-- When existing articles don't fully answer the question
-- When a customer asks something completely new
-- To track recurring questions that need dedicated articles
-
-WHY IT MATTERS:
-- Flagged questions appear in the admin "Knowledge Gaps" section
-- Helps prioritize which new articles to create
-- Builds a list of topics customers actually need
-- Improves the knowledge base over time`,
+**CALL THIS** when search_knowledge returns no results or low confidence.
+Flagged questions appear in admin "Knowledge Gaps" section.`,
     {
       query: z.string().describe('The question that could not be answered'),
-      reason: z.string().optional().describe('Reason why the question could not be answered'),
+      reason: z.string().optional().describe('Reason why'),
     },
     async (args) => {
       const result = await callRemoteServer('tools/call', {
@@ -242,29 +235,22 @@ WHY IT MATTERS:
     }
   );
 
-  // Tool 5: List Articles
+  // Tool 5: List Content (Unified - Articles + Q&A)
   server.tool(
-    'list_articles',
-    `Browse articles in the knowledge base with optional filtering.
+    'list_content',
+    `Browse content in the knowledge base with optional filtering.
 
-Parameters:
-- limit: Number of articles (default 10, max 50)
-- category: Filter by category slug (use list_categories first)
-
-Returns article ID, title, and summary for each match.
-Use get_article with the ID to retrieve full content.
-
-WORKFLOW:
-1. Call list_categories to discover available categories
-2. Call list_articles with specific category for focused results
-3. Call get_article for articles that look relevant`,
+Supports: articles, qa, or all (default).
+Use list_categories first to discover available categories.`,
     {
-      limit: z.number().optional().describe('Number of articles to return (max 50)'),
+      type: z.enum(['articles', 'qa', 'all']).optional().describe('Content type (default: all)'),
+      limit: z.number().optional().describe('Number of items (default: 10, max: 50)'),
       category: z.string().optional().describe('Filter by category slug'),
+      status: z.string().optional().describe('Filter Q&A by status: pending, draft, published'),
     },
     async (args) => {
       const result = await callRemoteServer('tools/call', {
-        name: 'list_articles',
+        name: 'list_content',
         arguments: args,
       }) as { content: Array<{ type: 'text'; text: string }> };
       return result;
@@ -274,7 +260,7 @@ WORKFLOW:
   // Tool 6: Health Check
   server.tool(
     'health_check',
-    'Check the health status of the memory system.',
+    'Check the health status of the memory system including article/Q&A counts.',
     {},
     async () => {
       const result = await callRemoteServer('tools/call', {
@@ -288,22 +274,8 @@ WORKFLOW:
   // Tool 7: List Categories
   server.tool(
     'list_categories',
-    `List all categories in the knowledge base with article counts.
-
-CRITICAL FOR EFFICIENT SEARCH:
-Categories help you quickly narrow down to relevant content.
-
-Returns for each category:
-- slug: Category identifier for filtering
-- name: Human-readable name
-- count: Number of articles
-- description: What the category covers
-
-RECOMMENDED WORKFLOW:
-1. Call list_categories to see what's available
-2. Call list_articles with category slug
-3. Call get_article for full content
-4. Or use search_knowledge for semantic search across all`,
+    `List all categories in the knowledge base with content counts.
+Use category slugs with list_content for filtered browsing.`,
     {},
     async () => {
       const result = await callRemoteServer('tools/call', {
@@ -315,21 +287,219 @@ RECOMMENDED WORKFLOW:
   );
 
   // ============================================================
-  // FULL MODE TOOLS (only available with --full flag or MCP_MODE=full)
+  // KNOWLEDGE GRAPH TOOLS (available in all modes)
+  // ============================================================
+
+  // Tool 8: Find Related Articles
+  server.tool(
+    'find_related',
+    'Find articles related through shared entities or explicit relationships. Uses graph traversal.',
+    {
+      article_id: z.string().describe('Article ID to find relations for'),
+      max_depth: z.number().optional().describe('Relationship hops 1-5 (default: 2)'),
+      min_strength: z.number().optional().describe('Min strength 0-1 (default: 0.3)'),
+      limit: z.number().optional().describe('Max articles (default: 10)'),
+    },
+    async (args) => {
+      const result = await callRemoteServer('tools/call', {
+        name: 'find_related',
+        arguments: args,
+      }) as { content: Array<{ type: 'text'; text: string }> };
+      return result;
+    }
+  );
+
+  // Tool 9: Get Entities
+  server.tool(
+    'get_entities',
+    'Get named entities from an article (people, orgs, forms, states, etc.).',
+    {
+      article_id: z.string().describe('Article ID to get entities for'),
+    },
+    async (args) => {
+      const result = await callRemoteServer('tools/call', {
+        name: 'get_entities',
+        arguments: args,
+      }) as { content: Array<{ type: 'text'; text: string }> };
+      return result;
+    }
+  );
+
+  // Tool 10: Search Entities
+  server.tool(
+    'search_entities',
+    'Search for entities by name or type across the knowledge base.',
+    {
+      query: z.string().optional().describe('Search query for entity name'),
+      type: z.string().optional().describe('Filter: PERSON, ORGANIZATION, FORM, STATE, COUNTRY, DATE, AMOUNT, CONCEPT, REGULATION, SERVICE, DOCUMENT'),
+      limit: z.number().optional().describe('Max entities (default: 20)'),
+    },
+    async (args) => {
+      const result = await callRemoteServer('tools/call', {
+        name: 'search_entities',
+        arguments: args,
+      }) as { content: Array<{ type: 'text'; text: string }> };
+      return result;
+    }
+  );
+
+  // Tool 11: Get Knowledge Graph
+  server.tool(
+    'get_knowledge_graph',
+    'Get the knowledge graph structure for visualization. Returns nodes and edges.',
+    {
+      center_article_id: z.string().optional().describe('Center on this article'),
+      depth: z.number().optional().describe('Traversal depth 1-5 (default: 2)'),
+      include_entities: z.boolean().optional().describe('Include entity nodes (default: true)'),
+      include_metadata: z.boolean().optional().describe('Include full metadata (default: false)'),
+      limit: z.number().optional().describe('Max nodes (default: 20, max: 100)'),
+    },
+    async (args) => {
+      const result = await callRemoteServer('tools/call', {
+        name: 'get_knowledge_graph',
+        arguments: args,
+      }) as { content: Array<{ type: 'text'; text: string }> };
+      return result;
+    }
+  );
+
+  // ============================================================
+  // EPISODIC MEMORY TOOLS (available in all modes)
+  // ============================================================
+
+  // Tool 12: Start Conversation
+  server.tool(
+    'start_conversation',
+    `Start a new conversation for tracking episodic memory.
+Call at the beginning of each session to enable context continuity.`,
+    {
+      session_id: z.string().describe('Session ID (e.g., MCP session ID)'),
+      title: z.string().optional().describe('Conversation title'),
+      user_id: z.string().optional().describe('User ID for multi-user tracking'),
+    },
+    async (args) => {
+      const result = await callRemoteServer('tools/call', {
+        name: 'start_conversation',
+        arguments: args,
+      }) as { content: Array<{ type: 'text'; text: string }> };
+      return result;
+    }
+  );
+
+  // Tool 13: Add Message
+  server.tool(
+    'add_message',
+    `Add a message to an existing conversation.
+Call after each user message and assistant response.
+User facts are automatically extracted.`,
+    {
+      conversation_id: z.string().describe('Conversation ID from start_conversation'),
+      role: z.enum(['user', 'assistant', 'system']).describe('Message role'),
+      content: z.string().describe('Message content'),
+      referenced_articles: z.string().optional().describe('Comma-separated article IDs referenced'),
+    },
+    async (args) => {
+      const result = await callRemoteServer('tools/call', {
+        name: 'add_message',
+        arguments: args,
+      }) as { content: Array<{ type: 'text'; text: string }> };
+      return result;
+    }
+  );
+
+  // Tool 14: Get Conversation
+  server.tool(
+    'get_conversation',
+    'Retrieve a conversation with all its messages by ID.',
+    {
+      conversation_id: z.string().describe('Conversation ID'),
+    },
+    async (args) => {
+      const result = await callRemoteServer('tools/call', {
+        name: 'get_conversation',
+        arguments: args,
+      }) as { content: Array<{ type: 'text'; text: string }> };
+      return result;
+    }
+  );
+
+  // Tool 15: List Conversations
+  server.tool(
+    'list_conversations',
+    'List conversations for a session or user. Returns recent first.',
+    {
+      session_id: z.string().optional().describe('Filter by session ID'),
+      user_id: z.string().optional().describe('Filter by user ID'),
+      limit: z.number().optional().describe('Max conversations (default: 20)'),
+    },
+    async (args) => {
+      const result = await callRemoteServer('tools/call', {
+        name: 'list_conversations',
+        arguments: args,
+      }) as { content: Array<{ type: 'text'; text: string }> };
+      return result;
+    }
+  );
+
+  // Tool 16: Get Session Context
+  server.tool(
+    'get_session_context',
+    `Get recent conversation context for a session.
+Call when user refers to prior conversation or asks follow-up questions.`,
+    {
+      session_id: z.string().describe('Session ID to get context for'),
+      message_limit: z.number().optional().describe('Max messages (default: 10)'),
+    },
+    async (args) => {
+      const result = await callRemoteServer('tools/call', {
+        name: 'get_session_context',
+        arguments: args,
+      }) as { content: Array<{ type: 'text'; text: string }> };
+      return result;
+    }
+  );
+
+  // ============================================================
+  // Q&A TOOLS (available in all modes)
+  // ============================================================
+
+  // Tool 17: Add Question
+  server.tool(
+    'add_question',
+    `Add a new question to the Q&A store for later answering.
+Use to capture questions from external channels.`,
+    {
+      question: z.string().describe('The question text'),
+      category: z.string().optional().describe('Category slug'),
+      tags: z.string().optional().describe('Comma-separated tags'),
+      priority: z.string().optional().describe('Priority: low, medium, high, critical'),
+      source: z.string().optional().describe('Source: mcp, email, manual, import'),
+    },
+    async (args) => {
+      const result = await callRemoteServer('tools/call', {
+        name: 'add_question',
+        arguments: args,
+      }) as { content: Array<{ type: 'text'; text: string }> };
+      return result;
+    }
+  );
+
+  // ============================================================
+  // FULL MODE TOOLS (only with --full flag or MCP_MODE=full)
   // ============================================================
 
   if (isFullMode) {
-    // Tool 8: Add Article
+    // Tool 18: Add Article
     server.tool(
       'add_article',
-      'Create a new article in the knowledge base. Automatically generates embedding for semantic search.',
+      'Create a new article in the knowledge base. Generates embedding automatically.',
       {
         title: z.string().describe('Article title'),
-        content: z.string().describe('Article content in markdown format'),
-        summary: z.string().optional().describe('Brief summary (auto-generated if not provided)'),
-        category: z.string().optional().describe('Category (e.g., federal-tax, state-compliance)'),
+        content: z.string().describe('Article content in markdown'),
+        summary: z.string().optional().describe('Brief summary (auto-generated if omitted)'),
+        category: z.string().optional().describe('Category slug'),
         tags: z.string().optional().describe('Comma-separated tags'),
-        source: z.string().optional().describe('Source of the article (e.g., manual, irs.gov)'),
+        source: z.string().optional().describe('Source (e.g., manual, irs.gov)'),
       },
       async (args) => {
         const result = await callRemoteServer('tools/call', {
@@ -340,7 +510,7 @@ RECOMMENDED WORKFLOW:
       }
     );
 
-    // Tool 9: Edit Article
+    // Tool 19: Edit Article
     server.tool(
       'edit_article',
       'Update an existing article. Re-generates embedding if content changes.',
@@ -361,13 +531,13 @@ RECOMMENDED WORKFLOW:
       }
     );
 
-    // Tool 10: Remove Article
+    // Tool 20: Remove Article
     server.tool(
       'remove_article',
-      'Soft-delete an article from the knowledge base. Article is marked as deleted but not permanently removed.',
+      'Soft-delete an article. Marked as deleted but not permanently removed.',
       {
         article_id: z.string().describe('Article ID to remove'),
-        reason: z.string().optional().describe('Reason for deletion (for audit log)'),
+        reason: z.string().optional().describe('Reason for deletion'),
       },
       async (args) => {
         const result = await callRemoteServer('tools/call', {
@@ -378,14 +548,14 @@ RECOMMENDED WORKFLOW:
       }
     );
 
-    // Tool 11: Rate Answer
+    // Tool 21: Rate Answer
     server.tool(
       'rate_answer',
-      'Rate a previous answer as helpful, unhelpful, or neutral. Helps improve the knowledge base.',
+      'Rate a previous answer as helpful, unhelpful, or neutral.',
       {
-        query_id: z.string().describe('Query log ID from a previous answer_question response'),
+        query_id: z.string().describe('Query log ID from answer_question'),
         rating: z.number().describe('Rating: -1 (unhelpful), 0 (neutral), 1 (helpful)'),
-        feedback: z.string().optional().describe('Optional text feedback'),
+        feedback: z.string().optional().describe('Optional feedback text'),
       },
       async (args) => {
         const result = await callRemoteServer('tools/call', {