@pragmatic-growth/memory-mcp 3.2.0 → 3.3.0

package/README.md

@@ -40,7 +40,8 @@ For clients that only support stdio (Raycast, local tools):
 ## Operating Mode
 
 PG-Memory provides a **personal knowledge base** focused on semantic search and content retrieval:
-- **Core Knowledge**: search, get content, list content, list categories, health check, log unanswered
+- **Core Knowledge**: search, get content, list content, list categories, health check, smart gap logging
+- **AI-Powered**: Automatic question quality evaluation, deduplication, and priority assignment
 
 All tools are available by default - no special flags required.
 
@@ -79,24 +80,27 @@ CLERK_API_KEY=your-key memory-mcp
 | `CLERK_API_KEY` | Yes | Clerk API key for authentication |
 | `MCP_SERVER_URL` | No | Custom server URL (default: production) |
 
-## Available Tools (6 Total)
+## Available Tools (7 Total)
 
-The tool list below reflects the current minimal, token-efficient MCP architecture.
+The tool list below reflects the current token-efficient MCP architecture with AI-powered question handling.
 
 | Tool | Description |
 |------|-------------|
+| `__IMPORTANT` | Workflow instructions (3-layer pattern: search → get_content → smart_log_gap) |
 | `search_knowledge` | Semantic search across articles (returns metadata only - use get_content for full text) |
 | `get_content` | Retrieve full article content by ID |
+| `smart_log_gap` | AI-evaluated gap logging with deduplication, quality filtering, and priority assignment |
 | `list_content` | Browse articles with filtering (by type, category, status) |
 | `list_categories` | List all knowledge base categories |
 | `health_check` | System health status and statistics |
-| `log_unanswered` | Flag knowledge gaps when search returns no results |
 
 ## Architecture Philosophy
 
 **Token Efficiency**: Following claude-mem's pattern, `search_knowledge` returns only metadata (ID, title, similarity). Use `get_content` to fetch full article text on-demand.
 
-**Simplicity**: 6 focused tools instead of 15+ complex ones. Personal knowledge base, not a SaaS platform.
+**AI-Powered Quality**: `smart_log_gap` uses LLM evaluation to filter spam, detect duplicates (>85% similarity), suggest existing answers (>70% match), and auto-assign priority.
+
+**Simplicity**: 7 focused tools instead of 15+ complex ones. Personal knowledge base with intelligent question handling.
 
 ## How It Works
 
@@ -112,7 +116,19 @@ This package runs locally as a stdio MCP server and proxies requests to the remo
 
 ## Changelog
 
-### v3.2.0 (Latest)
+### v3.3.0 (Latest)
+- **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

package/dist/index.d.ts

@@ -7,8 +7,6 @@
  *
  * Usage:
  *   npx @pragmatic-growth/memory-mcp             # Read-only mode (default)
- *   npx @pragmatic-growth/memory-mcp --full      # Full mode with edit capabilities
- *   npx @pragmatic-growth/memory-mcp --edit      # Alias for --full
  *
  * Environment variables:
  *   CLERK_API_KEY - Clerk API key for authentication (required)

package/dist/index.js

@@ -7,8 +7,6 @@
  *
  * Usage:
  *   npx @pragmatic-growth/memory-mcp             # Read-only mode (default)
- *   npx @pragmatic-growth/memory-mcp --full      # Full mode with edit capabilities
- *   npx @pragmatic-growth/memory-mcp --edit      # Alias for --full
  *
  * Environment variables:
  *   CLERK_API_KEY - Clerk API key for authentication (required)
@@ -21,10 +19,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-// Parse CLI arguments for mode
-const args = process.argv.slice(2);
-const hasFullFlag = args.includes('--full') || args.includes('--edit');
-const isFullMode = hasFullFlag;
 // Configuration
 const SERVER_URL = process.env.MCP_SERVER_URL || 'https://memory.pragmaticgrowth.com/mcp';
 const API_KEY = process.env.CLERK_API_KEY;
@@ -49,9 +43,6 @@ async function callRemoteServer(method, params) {
     if (sessionId) {
         headers['Mcp-Session-Id'] = sessionId;
     }
-    if (isFullMode) {
-        headers['Mcp-Mode'] = 'full';
-    }
     if (negotiatedProtocolVersion && method !== 'initialize') {
         headers['Mcp-Protocol-Version'] = negotiatedProtocolVersion;
     }
@@ -86,7 +77,7 @@ async function initializeRemoteSession() {
         capabilities: {},
         clientInfo: {
             name: 'pg-memory-stdio',
-            version: '3.2.0',
+            version: '3.3.0',
         },
     });
     if (typeof result === 'object' && result && 'protocolVersion' in result) {
@@ -100,7 +91,6 @@ async function initializeRemoteSession() {
  * Create and start the stdio MCP server.
  */
 async function main() {
-    const modeLabel = isFullMode ? 'full' : 'readonly';
     // Initialize remote session first
     try {
         await initializeRemoteSession();
@@ -112,12 +102,39 @@ async function main() {
     // Create local MCP server
     const server = new McpServer({
         name: 'pg-memory',
-        version: '3.2.0',
-        description: `PG-Memory knowledge base (${modeLabel} mode)`,
+        version: '3.3.0',
+        description: 'PG-Memory personal knowledge base with AI-powered question handling',
     });
     // ============================================================
     // CORE KNOWLEDGE TOOLS (available in all modes)
     // ============================================================
+    // Tool 0: __IMPORTANT - Workflow Instructions (pseudo-tool)
+    server.tool('__IMPORTANT', `3-LAYER WORKFLOW FOR QUESTION ANSWERING (ALWAYS FOLLOW):
+
+1. search_knowledge(query) → Get lightweight index with IDs (~50 tokens/result)
+   - Searches articles in knowledge base
+   - Returns: id, title, similarity, date
+   - DO NOT fetch full content yet
+
+2. get_content(id) → Fetch full content for filtered IDs only
+   - Only fetch what you need after reviewing search results
+   - Saves 10x tokens vs fetching all results
+
+3. smart_log_gap(question, context?) → Log unanswered questions
+   - AI evaluates quality, deduplicates, suggests existing answers
+   - Returns: {action: 'logged' | 'duplicate' | 'answered' | 'rejected'}
+   - NEVER log without searching first
+
+CRITICAL RULES:
+- NEVER fetch full content before reviewing search results
+- NEVER log gaps without searching first
+- ALWAYS check for duplicates using similarity`, {}, async () => {
+        const result = await callRemoteServer('tools/call', {
+            name: '__IMPORTANT',
+            arguments: {},
+        });
+        return result;
+    });
     // Tool 1: Search Knowledge
     server.tool('search_knowledge', `Search the knowledge base using semantic similarity.
 
@@ -138,10 +155,8 @@ Use get_content with the ID to retrieve full content.`, {
     // Tool 2: Get Content
     server.tool('get_content', `Retrieve complete article content from the knowledge base by ID.
 
-Use summary_only=true first to check content size, then fetch with max_length if needed.`, {
-        content_id: z.string().describe('Article ID (e.g., art_abc123)'),
-        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)'),
+Call this after reviewing search_knowledge results to fetch full content only for relevant articles.`, {
+        id: z.string().describe('Article ID from search results (e.g., art_abc123)'),
     }, async (args) => {
         const result = await callRemoteServer('tools/call', {
             name: 'get_content',
@@ -149,16 +164,28 @@ Use summary_only=true first to check content size, then fetch with max_length if
         });
         return result;
     });
-    // Tool 3: Log Unanswered
-    server.tool('log_unanswered', `Flag a question as unanswered for knowledge gap analysis.
+    // Tool 3: Smart Log Gap - AI-evaluated gap logging
+    server.tool('smart_log_gap', `Step 3: Log unanswered question with AI evaluation.
+
+SMART BEHAVIORS:
+- Checks for similar existing gaps (>85% = returns duplicate)
+- Checks for matching articles (>70% = suggests existing answer)
+- AI evaluates quality (filters garbage/spam)
+- Auto-assigns priority based on urgency signals
+
+ALWAYS search first before calling this. Do not log without searching.
 
-**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'),
+Returns one of:
+- {action: 'logged', gapId, priority, quality} - Question logged
+- {action: 'duplicate', existingGapId, similarity} - Duplicate detected  
+- {action: 'answered', articleId, title, similarity} - Already answered
+- {action: 'rejected', reason, quality} - Spam/garbage filtered`, {
+        question: z.string().describe('The unanswered question'),
+        context: z.string().optional().describe('Additional context (email subject, sender, etc)'),
+        source: z.enum(['mcp', 'email', 'chat']).optional().describe('Question source (default: mcp)'),
     }, async (args) => {
         const result = await callRemoteServer('tools/call', {
-            name: 'log_unanswered',
+            name: 'smart_log_gap',
             arguments: args,
         });
         return result;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pragmatic-growth/memory-mcp",
-  "version": "3.2.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. Personal knowledge base with 6 focused tools for semantic search and content retrieval.",
+  "version": "3.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. Personal knowledge base with 7 focused tools including AI-powered question handling with smart deduplication and quality filtering.",
   "main": "dist/index.js",
   "bin": {
     "memory-mcp": "dist/index.js"