@synth-coder/memhub 0.2.2 → 0.2.4

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);
+}
+
+/**
+ * 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 };
+
+  // Ensure mcpServers object exists
+  if (typeof result.mcpServers !== 'object' || result.mcpServers === null) {
+    result.mcpServers = {};
+  }
+
+  // Merge memhub server
+  const existingServers = result.mcpServers as Record<string, unknown>;
+  const newServers = newConfig.mcpServers as Record<string, unknown>;
+
+  for (const [serverName, serverConfig] of Object.entries(newServers)) {
+    existingServers[serverName] = serverConfig;
+  }
+
+  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 servers = existingConfig.mcpServers 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}`,
+  };
+}

package/src/cli/types.ts

@@ -0,0 +1,112 @@
+/**
+ * CLI types and constants
+ */
+
+export type AgentType =
+  | 'cursor'
+  | 'claude-code'
+  | 'cline'
+  | 'windsurf'
+  | 'factory-droid'
+  | 'gemini-cli'
+  | 'codex';
+
+export interface AgentConfig {
+  readonly id: AgentType;
+  readonly name: string;
+  readonly description: string;
+  /** Local config file path (relative to project root) */
+  readonly configFile: string;
+  /** Global config file path (relative to home directory) */
+  readonly globalConfigFile: string;
+  readonly configFormat: 'json' | 'markdown' | 'toml';
+  /** Local instructions file path */
+  readonly instructionsFile: string;
+  /** Global instructions file path (relative to home directory) */
+  readonly globalInstructionsFile: string;
+  readonly instructionsFormat: 'markdown' | 'plain';
+}
+
+export const AGENTS: readonly AgentConfig[] = [
+  {
+    id: 'cursor',
+    name: 'Cursor',
+    description: 'AI code editor with MCP support',
+    configFile: '.cursor/mcp.json',
+    globalConfigFile: '.cursor/mcp.json',
+    configFormat: 'json',
+    instructionsFile: '.cursorrules',
+    globalInstructionsFile: '.cursorrules',
+    instructionsFormat: 'plain',
+  },
+  {
+    id: 'claude-code',
+    name: 'Claude Code',
+    description: 'Anthropic CLI for Claude',
+    configFile: '.mcp.json',
+    globalConfigFile: '.claude/settings.json',
+    configFormat: 'json',
+    instructionsFile: 'CLAUDE.md',
+    globalInstructionsFile: '.claude/CLAUDE.md',
+    instructionsFormat: 'markdown',
+  },
+  {
+    id: 'cline',
+    name: 'Cline',
+    description: 'VS Code extension for AI coding',
+    configFile: '.cline/mcp.json',
+    globalConfigFile: '.cline/mcp.json',
+    configFormat: 'json',
+    instructionsFile: '.clinerules',
+    globalInstructionsFile: '.clinerules',
+    instructionsFormat: 'plain',
+  },
+  {
+    id: 'windsurf',
+    name: 'Windsurf',
+    description: 'Codeium AI editor',
+    configFile: '.codeium/windsurf/mcp_config.json',
+    globalConfigFile: '.codeium/windsurf/mcp_config.json',
+    configFormat: 'json',
+    instructionsFile: '.windsurfrules',
+    globalInstructionsFile: '.windsurfrules',
+    instructionsFormat: 'plain',
+  },
+  {
+    id: 'factory-droid',
+    name: 'Factory Droid',
+    description: 'Factory AI coding agent',
+    configFile: '.factory/mcp.json',
+    globalConfigFile: '.factory/mcp.json',
+    configFormat: 'json',
+    instructionsFile: '.factory/AGENTS.md',
+    globalInstructionsFile: '.factory/AGENTS.md',
+    instructionsFormat: 'markdown',
+  },
+  {
+    id: 'gemini-cli',
+    name: 'Gemini CLI',
+    description: 'Google Gemini command line tool',
+    configFile: '.gemini/settings.json',
+    globalConfigFile: '.gemini/settings.json',
+    configFormat: 'json',
+    instructionsFile: 'GEMINI.md',
+    globalInstructionsFile: '.gemini/GEMINI.md',
+    instructionsFormat: 'markdown',
+  },
+  {
+    id: 'codex',
+    name: 'Codex',
+    description: 'OpenAI CLI coding agent',
+    configFile: '.codex/config.toml',
+    globalConfigFile: '.codex/config.toml',
+    configFormat: 'toml',
+    instructionsFile: 'AGENTS.md',
+    globalInstructionsFile: '.codex/AGENTS.md',
+    instructionsFormat: 'markdown',
+  },
+] as const;
+
+export function getAgentById(id: AgentType): AgentConfig | undefined {
+  return AGENTS.find(agent => agent.id === id);
+}

package/src/contracts/mcp.ts

@@ -220,4 +220,4 @@ export type ToolInput<T extends ToolName> = T extends 'memory_load'
         category?: string;
         importance?: number;
       }
-    : never;
+    : never;

package/src/contracts/schemas.ts

@@ -41,10 +41,10 @@ export const ImportanceSchema = z.number().int().min(1).max(5);
 
 /** STM memory entry type */
 export const MemoryEntryTypeSchema = z.enum([
-  'preference',  // User likes/dislikes
-  'decision',    // Technical choices with reasoning
-  'context',     // Project/environment information
-  'fact',        // Objective knowledge
+  'preference', // User likes/dislikes
+  'decision', // Technical choices with reasoning
+  'context', // Project/environment information
+  'fact', // Objective knowledge
 ]);
 
 // ============================================================================