@unifiedmemory/cli 1.2.0 → 1.3.1

package/.env.example

@@ -1,29 +1,44 @@
 # UnifiedMemory CLI Configuration
-# Copy this file to .env and fill in your values
+#
+# ============================================
+# IMPORTANT: This file is OPTIONAL
+# ============================================
+# The CLI includes production defaults for all values below.
+# This file is only needed if you want to override defaults
+# (e.g., for development, testing, or custom deployments).
+#
+# For normal usage, you can delete this file - the CLI will work without it.
+#
+# To use custom values:
+# 1. Copy this file to .env
+# 2. Uncomment and modify the values you want to override
+# 3. Leave other values commented to use the built-in defaults
 
 # ============================================
-# REQUIRED: Clerk OAuth Configuration
+# Clerk OAuth Configuration
 # ============================================
-# Get these from your Clerk dashboard: https://dashboard.clerk.com
-CLERK_CLIENT_ID=your_clerk_client_id_here
-CLERK_DOMAIN=your-app.clerk.accounts.dev
+# Production defaults are included in the CLI
+# Only override these if using a custom Clerk instance
+# CLERK_CLIENT_ID=custom_clerk_client_id
+# CLERK_DOMAIN=custom-app.clerk.accounts.dev
 
 # ============================================
-# REQUIRED: API Configuration
+# API Configuration
 # ============================================
-# Your UnifiedMemory API gateway URL
-API_ENDPOINT=https://your-api-gateway.zuplo.dev
+# Production default is included in the CLI
+# Only override this for local testing or custom deployments
+# API_ENDPOINT=https://custom-api-gateway.zuplo.dev
 
 # ============================================
-# OPTIONAL: OAuth Flow Configuration
+# OAuth Flow Configuration
 # ============================================
-# Customize the OAuth redirect URI and local server port
-# Default values work for most users
+# Defaults to localhost:3333 for the OAuth callback server
+# Customize only if you need a different port or URL
 # REDIRECT_URI=http://localhost:3333/callback
 # PORT=3333
 
 # ============================================
-# OPTIONAL: Clerk Client Secret
+# Clerk Client Secret (Optional)
 # ============================================
 # Not required for PKCE flow (recommended)
 # Only set this if specifically instructed

package/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **lib/config.js** - Embedded production defaults for zero-configuration installation
+  - Added default values for `CLERK_CLIENT_ID`, `CLERK_DOMAIN`, and `API_ENDPOINT`
+  - Users no longer need to create `.env` files after `npm install`
+  - Environment variables can still override defaults for development/testing
+  - Simplified `validateConfig()` to remove "missing environment variables" errors
+  - CLI now works immediately after installation with no setup required
+
+- **.env.example** - Updated documentation to clarify optional nature
+  - Added prominent note that the file is OPTIONAL
+  - Explained that production defaults are included in the CLI
+  - Commented out all example values to emphasize optional overrides
+  - Clarified when overrides might be needed (development, testing, custom deployments)
+
+- **README.md** - Improved installation and configuration documentation
+  - Added "No configuration required!" note to installation section
+  - Renamed "Configuration" to "Advanced Configuration (Optional)"
+  - Removed "Missing environment variables" from troubleshooting
+  - Emphasized zero-friction installation experience
+
 ## [1.2.0] - 2026-01-08
 
 ### Added

package/README.md

@@ -171,6 +171,8 @@ npm install -g @unifiedmemory/cli
 um --version
 ```
 
+**No configuration required!** The CLI includes production defaults and works immediately after installation.
+
 **Option 2: Use with npx (no installation)**
 ```bash
 npx @unifiedmemory/cli init
@@ -213,43 +215,35 @@ Tokens automatically refresh. If you see auth errors:
 um login
 ```
 
-### Missing environment variables
-If you see "Missing required environment variables" error:
-1. Copy `.env.example` to `.env` in the CLI installation directory
-2. Fill in your Clerk and API credentials
-3. See Configuration section below for details
+## Advanced Configuration (Optional)
 
-## Configuration
+**For most users, no configuration is needed!** The CLI includes production defaults and works out of the box.
 
-The CLI requires environment variables for Clerk OAuth and API access. These should never be hardcoded in your project.
+For development, testing, or custom deployments, you can override defaults by creating a `.env` file:
 
-**Step 1: Create `.env` file**
+**Step 1: Create `.env` file** (optional)
 ```bash
 # In the um-cli installation directory (find with: npm root -g)
 cp .env.example .env
 ```
 
-**Step 2: Add your credentials**
+**Step 2: Override the values you need** (optional)
 ```bash
-# Required: Clerk OAuth Configuration
-CLERK_CLIENT_ID=your_clerk_client_id_here
-CLERK_DOMAIN=your-app.clerk.accounts.dev
-
-# Required: API Configuration
-API_ENDPOINT=https://your-api-gateway.zuplo.dev
-```
+# Optional: Override production defaults
+CLERK_CLIENT_ID=custom_clerk_client_id
+CLERK_DOMAIN=custom-app.clerk.accounts.dev
+API_ENDPOINT=https://custom-api-gateway.zuplo.dev
 
-Get these values from:
-- **Clerk credentials**: [Clerk Dashboard](https://dashboard.clerk.com)
-- **API endpoint**: Your UnifiedMemory deployment
-
-**Optional configuration**:
-```bash
-# Customize OAuth redirect (defaults shown)
+# Optional: Customize OAuth redirect (defaults to localhost:3333)
 REDIRECT_URI=http://localhost:3333/callback
 PORT=3333
 ```
 
+**When you might need this**:
+- 🔧 **Development**: Testing with a local API backend
+- 🧪 **Testing**: Using a staging or test Clerk instance
+- 🏢 **Custom Deployment**: Running your own UnifiedMemory instance
+
 See `.env.example` for the complete template with documentation.
 
 ## Privacy & Security

package/commands/record.js

@@ -52,6 +52,7 @@ export async function record(summary, options = {}) {
     };
 
     // 5. Prepare tool arguments
+    // Note: headers (X-Org-Id, X-User-Id) are handled at HTTP level by authHeaders
     const toolArgs = {
       body: {
         summary_text: summary,
@@ -59,10 +60,6 @@ export async function record(summary, options = {}) {
         source: options.source || 'um-cli',
         confidence: options.confidence ? parseFloat(options.confidence) : 0.7,
         tags: options.tags ? options.tags.split(',') : []
-      },
-      headers: {
-        'X-Org-Id': tokenData.selectedOrg?.id || tokenData.decoded?.sub,
-        'X-User-Id': tokenData.decoded?.sub
       }
     };
 
@@ -89,22 +86,47 @@ export async function record(summary, options = {}) {
       projectContext
     );
 
-    // 7. Handle response
+    // 7. Handle response - validate success properly
     if (result.content && Array.isArray(result.content)) {
       const textContent = result.content.find(c => c.type === 'text');
       if (textContent) {
-        const response = JSON.parse(textContent.text);
-        console.log(chalk.green('✓ Note created successfully'));
-        console.log(chalk.gray(`  Note ID: ${response.note_id || 'N/A'}`));
-        if (response.confidence) {
-          console.log(chalk.gray(`  Confidence: ${response.confidence}`));
+        try {
+          const response = JSON.parse(textContent.text);
+
+          // Check for error in response
+          if (result.isError || response.error || response.detail) {
+            throw new Error(response.error || response.detail || 'Note creation failed');
+          }
+
+          console.log(chalk.green('✓ Note created successfully'));
+          console.log(chalk.gray(`  Note ID: ${response.note_id || 'N/A'}`));
+          if (response.confidence) {
+            console.log(chalk.gray(`  Confidence: ${response.confidence}`));
+          }
+          return response;
+        } catch (parseError) {
+          if (parseError.message.includes('Note creation failed')) {
+            throw parseError;
+          }
+          throw new Error(`Failed to parse API response: ${parseError.message}`);
         }
-        return response;
       }
     }
 
-    console.log(chalk.green('✓ Note created'));
-    return result;
+    // Check for direct note response (some backends return this directly)
+    if (result.note_id) {
+      console.log(chalk.green('✓ Note created successfully'));
+      console.log(chalk.gray(`  Note ID: ${result.note_id}`));
+      return result;
+    }
+
+    // Check for error indicators
+    if (result.error || result.detail || result.isError) {
+      throw new Error(result.error || result.detail || 'Note creation failed');
+    }
+
+    // Unknown response format - fail explicitly instead of silent success
+    throw new Error('Unexpected response format from API');
 
   } catch (error) {
     console.error(chalk.red('✗ Failed to create note:'));

package/lib/config.js

@@ -9,49 +9,37 @@ const __dirname = dirname(__filename);
 dotenvConfig({ path: join(__dirname, '..', '.env') });
 
 export const config = {
-  // Required: Clerk OAuth configuration
-  clerkClientId: process.env.CLERK_CLIENT_ID,
+  // Clerk OAuth configuration (production defaults, can be overridden via env vars)
+  clerkClientId: process.env.CLERK_CLIENT_ID || 'nULlnomaKB9rRGP2',
   clerkClientSecret: process.env.CLERK_CLIENT_SECRET, // Optional for PKCE flow
-  clerkDomain: process.env.CLERK_DOMAIN,
+  clerkDomain: process.env.CLERK_DOMAIN || 'clear-caiman-45.clerk.accounts.dev',
 
-  // Required: API configuration
-  apiEndpoint: process.env.API_ENDPOINT,
+  // API configuration (production default, can be overridden via env var)
+  apiEndpoint: process.env.API_ENDPOINT || 'https://rose-asp-main-1c0b114.d2.zuplo.dev',
 
-  // Optional: OAuth flow configuration (non-sensitive defaults OK)
+  // OAuth flow configuration (localhost defaults for callback server)
   redirectUri: process.env.REDIRECT_URI || 'http://localhost:3333/callback',
   port: parseInt(process.env.PORT || '3333', 10)
 };
 
-// Validation function - ensures required configuration is present
+// Validation function - validates configuration values
 export function validateConfig() {
-  const missing = [];
-
-  if (!config.clerkClientId) {
-    missing.push('CLERK_CLIENT_ID');
-  }
-
-  if (!config.clerkDomain) {
-    missing.push('CLERK_DOMAIN');
-  }
-
-  if (!config.apiEndpoint) {
-    missing.push('API_ENDPOINT');
-  }
-
-  if (missing.length > 0) {
-    throw new Error(
-      `Missing required environment variables: ${missing.join(', ')}\n\n` +
-      `Please create a .env file in the project root with these values.\n` +
-      `See .env.example for a template.`
-    );
-  }
-
-  // Validate URL format for apiEndpoint
+  // Validate URL format for apiEndpoint (now guaranteed to exist via defaults)
   try {
     new URL(config.apiEndpoint);
   } catch (e) {
     throw new Error(`API_ENDPOINT must be a valid URL (got: ${config.apiEndpoint})`);
   }
 
+  // Validate clerkDomain is not empty (basic sanity check)
+  if (!config.clerkDomain || config.clerkDomain.trim() === '') {
+    throw new Error('CLERK_DOMAIN cannot be empty');
+  }
+
+  // Validate clerkClientId is not empty (basic sanity check)
+  if (!config.clerkClientId || config.clerkClientId.trim() === '') {
+    throw new Error('CLERK_CLIENT_ID cannot be empty');
+  }
+
   return true;
 }

package/lib/mcp-proxy.js

@@ -14,6 +14,23 @@ function transformToolSchema(tool) {
   // Deep clone to avoid mutations
   const transformed = JSON.parse(JSON.stringify(tool));
 
+  // Remove headers entirely - proxy handles all headers at HTTP level
+  // AI never needs to provide X-Org-Id, X-User-Id, etc.
+  if (transformed.inputSchema?.properties?.headers) {
+    delete transformed.inputSchema.properties.headers;
+
+    // Also remove from required array if present
+    if (transformed.inputSchema.required && Array.isArray(transformed.inputSchema.required)) {
+      transformed.inputSchema.required = transformed.inputSchema.required.filter(
+        field => field !== 'headers'
+      );
+
+      if (transformed.inputSchema.required.length === 0) {
+        delete transformed.inputSchema.required;
+      }
+    }
+  }
+
   // Check if tool has pathParams in schema
   if (!transformed.inputSchema?.properties?.pathParams) {
     return transformed;
@@ -79,22 +96,31 @@ function injectContextParams(args, authContext, projectContext) {
     injected.pathParams = {};
   }
 
+  // Ensure headers object exists (gateway expects these in tool args)
+  if (!injected.headers) {
+    injected.headers = {};
+  }
+
   // Inject user ID from decoded JWT
   if (authContext?.decoded?.sub) {
     injected.pathParams.user = authContext.decoded.sub;
+    injected.headers['X-User-Id'] = authContext.decoded.sub;
   }
 
   // Inject org ID (from selectedOrg or fallback to user ID for personal account)
   if (authContext?.selectedOrg?.id) {
     injected.pathParams.org = authContext.selectedOrg.id;
+    injected.headers['X-Org-Id'] = authContext.selectedOrg.id;
   } else if (authContext?.decoded?.sub) {
     // Fallback to user ID for personal account context
     injected.pathParams.org = authContext.decoded.sub;
+    injected.headers['X-Org-Id'] = authContext.decoded.sub;
   }
 
   // Inject project ID from project config
   if (projectContext?.project_id) {
     injected.pathParams.proj = projectContext.project_id;
+    injected.headers['X-Project-Id'] = projectContext.project_id;
   }
 
   return injected;

package/lib/memory-instructions.js

@@ -1,72 +1,82 @@
 // Unique marker to detect if instructions already present
-export const MEMORY_INSTRUCTIONS_MARKER = '<!-- UNIFIEDMEMORY_INSTRUCTIONS_V1 -->';
+export const MEMORY_INSTRUCTIONS_MARKER = '<!-- UNIFIEDMEMORY_INSTRUCTIONS_V2 -->';
 
 export function getMemoryInstructions() {
   return `${MEMORY_INSTRUCTIONS_MARKER}
 
-# UnifiedMemory Automatic Integration
+# UnifiedMemory Integration (REQUIRED)
 
-When working in this project, automatically integrate with UnifiedMemory to maintain project knowledge:
+This project uses UnifiedMemory for persistent knowledge management. The \`unifiedmemory\` MCP server is configured and MUST be used for all relevant queries.
 
-## 1. Search Before Responding
+## Available Tools
 
-**When**: User submits any query or request
-**Action**: Use the \`unifiedmemory\` MCP tool to search for relevant context
-**Usage**:
-- Send the user's query to the search tool
-- Review the search results for relevant prior work, decisions, or context
-- Incorporate findings into your response
+The \`unifiedmemory\` MCP server provides these tools (call them like any MCP tool):
 
-Example:
-\`\`\`
-User: "Add dark mode to the dashboard"
-→ Search: unifiedmemory search --query "dark mode dashboard styling"
-→ Review results for existing patterns or decisions
-→ Respond with context-aware answer
-\`\`\`
+| Tool | Purpose | Required Parameters |
+|------|---------|---------------------|
+| \`search_notes\` | **Primary tool** - Search project knowledge base | \`query\` (search text) |
+| \`create_note\` | Record decisions, plans, or completions | \`summary_text\`, \`topic\` |
+| \`list_notes\` | List all notes in current project | None |
+| \`get_note\` | Retrieve a specific note by ID | \`note_id\` |
+| \`list_topics\` | List available topics/categories | None |
+| \`create_topic\` | Create a new topic for organization | \`name\` |
+| \`list_projects\` | List available projects | None |
 
-## 2. Record Plans
+All tools automatically use the correct project context - no additional configuration needed.
 
-**When**: Creating an implementation plan or design approach
-**Action**: Record the plan as a note using the \`unifiedmemory\` tool
-**Format**:
-- Include: objective, approach, key steps, important decisions
-- Keep concise but informative
-- Limit to under 1000 characters for optimal indexing
+## MANDATORY: Search Before Implementing
 
-Example:
-\`\`\`
-Plan created for dark mode feature
-→ unifiedmemory create_note --content "Plan: Dark mode implementation. Approach: CSS variables + localStorage persistence. Steps: 1) Define color tokens, 2) Add toggle component, 3) Persist preference. Decision: Use system preference as default."
-\`\`\`
+**REQUIREMENT**: Before responding to ANY coding task, feature request, or implementation question, you MUST:
+
+1. Call the \`search_notes\` tool with the user's query or relevant keywords
+2. Review returned results for prior decisions, patterns, or context
+3. Incorporate relevant findings into your response
+4. Mention what context you found (or didn't find) in your response
+
+### When to Search
 
-## 3. Record Task Completions
+You MUST search before:
+- Implementing any feature (search for existing patterns)
+- Fixing any bug (search for related issues)
+- Answering architecture questions (search for design decisions)
+- Modifying any component (search for existing conventions)
+- ANY coding task, no exceptions
 
-**When**: After completing any task, feature, or significant milestone
-**Action**: Create a summary note using the \`unifiedmemory\` tool
-**Format**:
-- Summarize what was accomplished and why
-- Include key technical decisions or gotchas
-- **IMPORTANT**: Limit to under 1000 characters
-- Focus on outcomes, not detailed code
+### Example Workflow
 
-Example:
 \`\`\`
-Completed dark mode feature
-→ unifiedmemory create_note --content "Completed: Dark mode toggle in dashboard. Implemented CSS custom properties with theme switcher component. User preference stored in localStorage. Respects system prefers-color-scheme by default. All components updated to use theme tokens."
+User: "Add authentication to the API"
+
+Step 1: Call search_notes with query "authentication API security"
+Step 2: Review results - found: "Decision: Use JWT with refresh tokens"
+Step 3: Implement following the established pattern
+Step 4: Respond: "Based on prior decisions in UnifiedMemory, I'll use JWT..."
 \`\`\`
 
-## Summary Guidelines
+## Do NOT Skip These Tools
+
+- ❌ NEVER start implementing without calling \`search_notes\` first
+- ❌ NEVER assume patterns without checking the knowledge base
+- ❌ NEVER skip search for "simple" tasks - context always helps
+- ✅ ALWAYS search even if you think you know the answer
+- ✅ ALWAYS mention search results (or lack thereof) in your response
+- ✅ ALWAYS use these tools when they can provide relevant context
+
+## Recording Knowledge with create_note
+
+After completing significant work, use \`create_note\` to record:
+- Implementation decisions and rationale
+- Completed features or fixes
+- Architectural patterns established
+- Gotchas or lessons learned
+
+Keep notes concise (under 1000 characters) and focus on the "why" not the "what".
+
+## Additional Tools
 
-- ✅ **DO**: Search context before responding
-- ✅ **DO**: Record plans and completions automatically
-- ✅ **DO**: Keep notes under 1000 characters
-- ✅ **DO**: Focus on decisions, outcomes, and context
-- ❌ **DON'T**: Record trivial tasks (typo fixes, minor edits)
-- ❌ **DON'T**: Include full code in notes
-- ❌ **DON'T**: Duplicate information already in git commits
+Use \`list_topics\` to understand project organization, \`list_notes\` to browse available knowledge, and \`get_note\` to retrieve full details of relevant notes found via search.
 
 ---
-*Auto-generated by UnifiedMemory CLI v1.0*
+*UnifiedMemory CLI - Knowledge that persists*
 `;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unifiedmemory/cli",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "UnifiedMemory CLI - AI code assistant integration",
   "main": "index.js",
   "type": "module",