@synth-coder/memhub 0.2.3 → 0.2.5

package/src/cli/agents/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Agent configuration generators index
+ */
+
+export { generateCursorConfig } from './cursor.js';
+export { generateClaudeCodeConfig } from './claude-code.js';
+export { generateClineConfig } from './cline.js';
+export { generateWindsurfConfig } from './windsurf.js';
+export { generateFactoryDroidConfig } from './factory-droid.js';
+export { generateGeminiCliConfig } from './gemini-cli.js';
+export { generateCodexConfig } from './codex.js';
+
+import type { AgentType } from '../types.js';
+import { generateCursorConfig } from './cursor.js';
+import { generateClaudeCodeConfig } from './claude-code.js';
+import { generateClineConfig } from './cline.js';
+import { generateWindsurfConfig } from './windsurf.js';
+import { generateFactoryDroidConfig } from './factory-droid.js';
+import { generateGeminiCliConfig } from './gemini-cli.js';
+import { generateCodexConfig } from './codex.js';
+
+export type ConfigGenerator = (memhubPath: string) => Record<string, unknown>;
+
+const generators: Record<AgentType, ConfigGenerator> = {
+  cursor: generateCursorConfig,
+  'claude-code': generateClaudeCodeConfig,
+  cline: generateClineConfig,
+  windsurf: generateWindsurfConfig,
+  'factory-droid': generateFactoryDroidConfig,
+  'gemini-cli': generateGeminiCliConfig,
+  codex: generateCodexConfig,
+};
+
+export function getConfigGenerator(agentId: AgentType): ConfigGenerator {
+  return generators[agentId];
+}

package/src/cli/agents/windsurf.ts

@@ -0,0 +1,14 @@
+/**
+ * Windsurf MCP configuration generator
+ */
+
+export function generateWindsurfConfig(_memhubPath: string): Record<string, unknown> {
+  return {
+    mcpServers: {
+      memhub: {
+        command: 'npx',
+        args: ['-y', '@synth-coder/memhub@latest'],
+      },
+    },
+  };
+}

package/src/cli/index.ts

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * MemHub CLI entry point
+ * - No args: start MCP server
+ * - With args: run CLI commands
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import * as p from '@clack/prompts';
+import { AGENTS, type AgentType } from './types.js';
+import { initAgent, selectAgentInteractive } from './init.js';
+import { createMcpServer } from '../server/mcp-server.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+interface PackageJson {
+  version?: string;
+}
+
+// Get package version
+let packageJsonPath = join(__dirname, '../../../package.json');
+if (!existsSync(packageJsonPath)) {
+  packageJsonPath = join(__dirname, '../../package.json');
+}
+
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8')) as PackageJson;
+const VERSION = packageJson.version || '0.0.0';
+
+/**
+ * Start MCP server (no args mode)
+ */
+async function startMcpServer(): Promise<void> {
+  const server = createMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('MemHub MCP Server running on stdio');
+}
+
+function printHelp(): void {
+  // eslint-disable-next-line no-console
+  console.log(`
+MemHub CLI v${VERSION} - Git-friendly memory for AI agents
+
+Usage:
+  memhub                    Start MCP server (default)
+  memhub init [options]     Configure MemHub for your AI agent
+  memhub --help             Show this help message
+  memhub --version          Show version
+
+Options:
+  -a, --agent <agent>       Agent type (skip interactive selection)
+  -f, --force               Update existing configuration
+  -l, --local               Configure for current project (default: global)
+
+Supported agents:
+${AGENTS.map(a => `  ${a.id.padEnd(15)} ${a.name}`).join('\n')}
+
+Examples:
+  memhub                               # Start MCP server
+  memhub init                          # Interactive selection (global)
+  memhub init --local                  # Interactive selection (project)
+  memhub init --agent cursor           # Configure for Cursor (global)
+  memhub init -a claude-code -l        # Configure for Claude Code (project)
+`);
+}
+
+function printVersion(): void {
+  // eslint-disable-next-line no-console
+  console.log(`MemHub CLI v${VERSION}`);
+}
+
+function parseAgent(value: string): AgentType | null {
+  const validAgents = AGENTS.map(a => a.id);
+  if (validAgents.includes(value as AgentType)) {
+    return value as AgentType;
+  }
+  console.error(`Invalid agent: ${value}`);
+  console.error(`Valid agents: ${validAgents.join(', ')}`);
+  return null;
+}
+
+async function runCli(args: string[]): Promise<void> {
+  // Parse command
+  const command = args[0];
+
+  if (command === '--help' || command === '-h') {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (command === '--version' || command === '-v') {
+    printVersion();
+    process.exit(0);
+  }
+
+  if (command !== 'init') {
+    p.log.error(`Unknown command: ${command}`);
+    p.log.info('Run "memhub --help" for usage information.');
+    process.exit(1);
+  }
+
+  // Parse init options
+  let agent: AgentType | undefined;
+  let force = false;
+  let local = false;
+
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '-a' || arg === '--agent') {
+      const value = args[++i];
+      if (!value) {
+        p.log.error('--agent requires a value');
+        process.exit(1);
+      }
+      const parsed = parseAgent(value);
+      if (!parsed) {
+        process.exit(1);
+      }
+      agent = parsed;
+    } else if (arg === '-f' || arg === '--force') {
+      force = true;
+    } else if (arg === '-l' || arg === '--local') {
+      local = true;
+    } else {
+      p.log.error(`Unknown option: ${arg}`);
+      process.exit(1);
+    }
+  }
+
+  // Start interactive session
+  p.intro(`MemHub v${VERSION}`);
+
+  // If no agent specified, run interactive selection
+  if (!agent) {
+    const selectedAgent = await selectAgentInteractive();
+    if (!selectedAgent) {
+      p.cancel('Operation cancelled.');
+      process.exit(0);
+    }
+    agent = selectedAgent;
+  }
+
+  // Run init with spinner
+  const s = p.spinner();
+  s.start(`Configuring MemHub for ${agent}...`);
+
+  const result = initAgent({
+    agent,
+    force,
+    local,
+  });
+
+  if (result.success) {
+    s.stop(`Configured for ${result.agent.name}`);
+    p.log.success(`MCP config: ${result.configPath}`);
+
+    if (result.instructionsUpdated) {
+      p.log.success(`Instructions: ${result.instructionsPath} (${result.instructionsReason})`);
+    } else {
+      p.log.info(`Instructions: ${result.instructionsPath} (${result.instructionsReason})`);
+    }
+
+    p.outro(`Restart your agent to start using MemHub.`);
+  } else {
+    s.stop('Configuration failed');
+    p.log.error(result.error);
+    process.exit(1);
+  }
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+
+  // No args: start MCP server
+  if (args.length === 0) {
+    await startMcpServer();
+    return;
+  }
+
+  // With args: run CLI
+  await runCli(args);
+}
+
+main().catch(error => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/src/cli/init.ts

@@ -0,0 +1,218 @@
+/**
+ * Init command implementation
+ * Generates MCP configuration for different AI agents
+ */
+
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { homedir } from 'os';
+import * as p from '@clack/prompts';
+import { AGENTS, type AgentType, type AgentConfig, getAgentById } from './types.js';
+import { getConfigGenerator } from './agents/index.js';
+import { updateInstructionsContent } from './instructions.js';
+import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
+
+export interface InitOptions {
+  readonly agent: AgentType;
+  /** @deprecated Use local instead */
+  readonly projectPath?: string;
+  readonly force?: boolean;
+  readonly local?: boolean;
+}
+
+export interface InitResult {
+  readonly success: true;
+  readonly configPath: string;
+  readonly instructionsPath: string;
+  readonly instructionsUpdated: boolean;
+  readonly instructionsReason: string;
+  readonly agent: AgentConfig;
+}
+
+export interface InitError {
+  readonly success: false;
+  readonly error: string;
+}
+
+export type InitOutcome = InitResult | InitError;
+
+/**
+ * Parse config file content based on format
+ */
+function parseConfig(
+  content: string,
+  format: 'json' | 'markdown' | 'toml'
+): Record<string, unknown> {
+  if (format === 'toml') {
+    return parseToml(content) as Record<string, unknown>;
+  }
+  return JSON.parse(content) as Record<string, unknown>;
+}
+
+/**
+ * Stringify config to string based on format
+ */
+function stringifyConfig(
+  config: Record<string, unknown>,
+  format: 'json' | 'markdown' | 'toml'
+): string {
+  if (format === 'toml') {
+    return stringifyToml(config);
+  }
+  return JSON.stringify(config, null, 2);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function getTargetMcpKey(config: Record<string, unknown>): 'mcpServers' | 'mcp_servers' {
+  return isRecord(config.mcp_servers) ? 'mcp_servers' : 'mcpServers';
+}
+
+/**
+ * Merge memhub config into existing config
+ * Preserves all existing servers, adds/updates memhub
+ */
+function mergeMcpConfig(
+  existing: Record<string, unknown>,
+  newConfig: Record<string, unknown>
+): Record<string, unknown> {
+  const result = { ...existing };
+  const targetKey = getTargetMcpKey(newConfig);
+  const existingServers = isRecord(result[targetKey]) ? result[targetKey] : {};
+  const newServers = (newConfig[targetKey] as Record<string, unknown>) ?? {};
+  result[targetKey] = { ...existingServers, ...newServers };
+
+  return result;
+}
+
+/**
+ * Run interactive agent selection using clack
+ */
+export async function selectAgentInteractive(): Promise<AgentType | null> {
+  const selection = await p.select({
+    message: 'Select your AI agent',
+    options: AGENTS.map(agent => ({
+      value: agent.id,
+      label: agent.name,
+      hint: agent.description,
+    })),
+  });
+
+  if (p.isCancel(selection)) {
+    return null;
+  }
+
+  return selection;
+}
+
+/**
+ * Generate and write MCP configuration for the specified agent
+ */
+export function initAgent(options: InitOptions): InitOutcome {
+  const { agent, force = false, local = false, projectPath } = options;
+
+  const agentConfig = getAgentById(agent);
+  if (!agentConfig) {
+    return {
+      success: false,
+      error: `Unknown agent: ${agent}. Valid agents: ${AGENTS.map(a => a.id).join(', ')}`,
+    };
+  }
+
+  // Determine base path and file paths based on local flag
+  const basePath = projectPath ?? (local ? process.cwd() : homedir());
+  const configFile = local ? agentConfig.configFile : agentConfig.globalConfigFile;
+  const instructionsFile = local
+    ? agentConfig.instructionsFile
+    : agentConfig.globalInstructionsFile;
+
+  const configPath = join(basePath, configFile);
+  const configDir = dirname(configPath);
+  const instructionsPath = join(basePath, instructionsFile);
+  const instructionsDir = dirname(instructionsPath);
+
+  // Generate MCP configuration
+  const generator = getConfigGenerator(agent);
+  const newConfig = generator(basePath);
+
+  let finalConfig: Record<string, unknown>;
+
+  // Check if config already exists
+  const configFormat = agentConfig.configFormat;
+  if (existsSync(configPath)) {
+    if (force) {
+      // Force: still merge, but this updates memhub entry
+      try {
+        const existingContent = readFileSync(configPath, 'utf-8');
+        const existingConfig = parseConfig(existingContent, configFormat);
+        finalConfig = mergeMcpConfig(existingConfig, newConfig);
+      } catch {
+        // Invalid config, use new config
+        finalConfig = newConfig;
+      }
+    } else {
+      // No force: check if memhub already exists
+      try {
+        const existingContent = readFileSync(configPath, 'utf-8');
+        const existingConfig = parseConfig(existingContent, configFormat);
+        const targetKey = getTargetMcpKey(newConfig);
+        const servers = existingConfig[targetKey] as Record<string, unknown> | undefined;
+
+        if (servers && 'memhub' in servers) {
+          return {
+            success: false,
+            error: `MemHub is already configured in ${configFile}. Use --force to update.`,
+          };
+        }
+
+        // Merge with existing config
+        finalConfig = mergeMcpConfig(existingConfig, newConfig);
+      } catch {
+        return {
+          success: false,
+          error: `Failed to parse existing config at ${configFile}. Use --force to overwrite.`,
+        };
+      }
+    }
+  } else {
+    finalConfig = newConfig;
+  }
+
+  // Ensure directories exist
+  if (!existsSync(configDir)) {
+    mkdirSync(configDir, { recursive: true });
+  }
+  if (!existsSync(instructionsDir)) {
+    mkdirSync(instructionsDir, { recursive: true });
+  }
+
+  // Write MCP configuration
+  writeFileSync(configPath, stringifyConfig(finalConfig, configFormat), 'utf-8');
+
+  // Handle instructions file
+  let existingContent = '';
+  if (existsSync(instructionsPath)) {
+    existingContent = readFileSync(instructionsPath, 'utf-8');
+  }
+
+  const {
+    content: updatedContent,
+    updated: instructionsUpdated,
+    reason: instructionsReason,
+  } = updateInstructionsContent(existingContent, agentConfig);
+
+  if (instructionsUpdated || !existsSync(instructionsPath)) {
+    writeFileSync(instructionsPath, updatedContent, 'utf-8');
+  }
+
+  return {
+    success: true,
+    configPath: configFile,
+    instructionsPath: instructionsFile,
+    instructionsUpdated,
+    instructionsReason,
+    agent: agentConfig,
+  };
+}

package/src/cli/instructions.ts

@@ -0,0 +1,156 @@
+/**
+ * MemHub instructions generator
+ * Generates agent-specific instruction content with versioned tags
+ */
+
+import type { AgentConfig } from './types.js';
+
+const MEMHUB_VERSION = '0.2.3';
+
+const START_TAG = `<!-- MEMHUB:v${MEMHUB_VERSION}:START -->`;
+const END_TAG = '<!-- MEMHUB:END -->';
+
+/**
+ * Extract MemHub version from content if present
+ */
+export function extractMemHubVersion(content: string): string | null {
+  const match = content.match(/<!-- MEMHUB:v([\d.]+):START -->/);
+  return match ? match[1] : null;
+}
+
+/**
+ * Check if MemHub instructions exist and need update
+ */
+export function needsUpdate(content: string): boolean {
+  const version = extractMemHubVersion(content);
+  if (!version) return true;
+  return version !== MEMHUB_VERSION;
+}
+
+/**
+ * Generate MemHub instructions content
+ */
+export function generateInstructionsContent(agent: AgentConfig): string {
+  const isMarkdown = agent.instructionsFormat === 'markdown';
+
+  if (isMarkdown) {
+    return `${START_TAG}
+## MemHub - AI Memory System
+
+MemHub is a Git-friendly memory system for storing decisions, preferences, and reusable knowledge.
+
+### When to Call memory_load
+
+**Proactively call** memory_load in these scenarios:
+
+- Starting a new conversation or task
+- User mentions "before", "remember", "last time" keywords
+- Uncertain about user preferences or constraints
+- Need project context (tech stack, conventions, architecture)
+
+### When to Call memory_update
+
+**Proactively store** memories in these scenarios:
+
+- User explicitly expresses a preference ("I prefer functional components")
+- User makes a decision with reasoning ("Using PostgreSQL because...")
+- Discover important project context (tech stack, constraints, patterns)
+- User corrects your assumptions ("Actually, we don't use Redux")
+
+### Usage Principles
+
+1. **Load on demand** - Call memory_load at task start to get context
+2. **Store timely** - Call memory_update when learning valuable information
+3. **Query precisely** - Use tags to filter relevant memories
+4. **Describe concisely** - Be specific in content, helpful in title
+
+### Memory Types
+
+| entryType | Purpose |
+|-----------|---------|
+| preference | User preferences (coding style, framework choices) |
+| decision | Architecture decisions, technology choices |
+| context | Project context (team, processes, constraints) |
+| fact | Learned facts, important notes |
+
+${END_TAG}`;
+  }
+
+  // Plain text format (for .cursorrules, .clinerules, etc.)
+  return `${START_TAG}
+# MemHub - AI Memory System
+
+MemHub is a Git-friendly memory system for storing decisions, preferences, and reusable knowledge.
+
+## When to Call memory_load
+
+- Starting a new conversation or task
+- User mentions "before", "remember", "last time" keywords
+- Uncertain about user preferences or constraints
+- Need project context (tech stack, conventions, architecture)
+
+## When to Call memory_update
+
+- User explicitly expresses a preference
+- User makes a decision with reasoning
+- Discover important project context
+- User corrects your assumptions
+
+## Memory Types
+
+- preference: User preferences
+- decision: Architecture decisions
+- context: Project context
+- fact: Learned facts
+
+## Principle
+
+Will my future self benefit from knowing this? If yes, store it.
+
+${END_TAG}`;
+}
+
+/**
+ * Update instructions file content
+ * - If no MemHub section: prepend new instructions
+ * - If MemHub section exists and outdated: replace with new version
+ * - If MemHub section exists and current: no change
+ */
+export function updateInstructionsContent(
+  existingContent: string,
+  agent: AgentConfig
+): { content: string; updated: boolean; reason: string } {
+  const trimmedContent = existingContent.trim();
+  const hasMemHub = trimmedContent.includes('<!-- MEMHUB:');
+
+  if (!hasMemHub) {
+    // No MemHub section: prepend
+    const newInstructions = generateInstructionsContent(agent);
+    return {
+      content: `${newInstructions}\n\n${trimmedContent}`,
+      updated: true,
+      reason: 'MemHub instructions added',
+    };
+  }
+
+  const currentVersion = extractMemHubVersion(trimmedContent);
+  if (currentVersion === MEMHUB_VERSION) {
+    // Already up to date
+    return {
+      content: existingContent,
+      updated: false,
+      reason: 'Already up to date',
+    };
+  }
+
+  // Need to update: replace old section with new
+  const newInstructions = generateInstructionsContent(agent);
+  const pattern = /<!-- MEMHUB:v[\d.]+:START -->[\s\S]*?<!-- MEMHUB:END -->/;
+  const updatedContent = trimmedContent.replace(pattern, newInstructions);
+
+  return {
+    content: updatedContent,
+    updated: true,
+    reason: `Updated from v${currentVersion} to v${MEMHUB_VERSION}`,
+  };
+}