@synth-coder/memhub 0.2.2 → 0.2.3

package/src/index.ts

@@ -1,8 +1,8 @@
-/**
- * Main entry point exports
- */
-
-export * from './contracts/index.js';
-export * from './services/index.js';
-export * from './storage/index.js';
-export * from './utils/index.js';
+/**
+ * Main entry point exports
+ */
+
+export * from './contracts/index.js';
+export * from './services/index.js';
+export * from './storage/index.js';
+export * from './utils/index.js';

package/src/server/index.ts

@@ -1,5 +1,5 @@
-/**
- * Server exports
- */
-
-export * from './mcp-server.js';
+/**
+ * Server exports
+ */
+
+export * from './mcp-server.js';

package/src/server/mcp-server.ts

@@ -1,162 +1,186 @@
-#!/usr/bin/env node
-/**
- * MCP Server - Model Context Protocol server implementation
- * Uses @modelcontextprotocol/sdk for protocol handling
- */
-
-import { readFileSync, existsSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import {
-  CallToolRequestSchema,
-  ListToolsRequestSchema,
-} from '@modelcontextprotocol/sdk/types.js';
-import { MemoryService, ServiceError } from '../services/memory-service.js';
-import {
-  MemoryLoadInputSchema,
-  MemoryUpdateInputV2Schema,
-} from '../contracts/schemas.js';
-import { TOOL_DEFINITIONS, SERVER_INFO } from '../contracts/mcp.js';
-import { ErrorCode } from '../contracts/types.js';
-
-// Get package version
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-interface PackageJson {
-  version?: string;
-}
-
-// npm package runtime: dist/src/server -> package root
-// test runtime: src/server -> package root
-let packageJsonPath = join(__dirname, '../../../package.json');
-if (!existsSync(packageJsonPath)) {
-  // Fallback for test environment (running from src/)
-  packageJsonPath = join(__dirname, '../../package.json');
-}
-
-const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8')) as PackageJson;
-
-/**
- * Create McpServer instance using SDK
- */
-export function createMcpServer(): Server {
-  const storagePath = process.env.MEMHUB_STORAGE_PATH || './memories';
-  const vectorSearch = process.env.MEMHUB_VECTOR_SEARCH !== 'false';
-  const memoryService = new MemoryService({ storagePath, vectorSearch });
-
-  // Create server using SDK
-  const server = new Server(
-    {
-      name: SERVER_INFO.name,
-      version: packageJson.version || SERVER_INFO.version,
-    },
-    {
-      capabilities: {
-        tools: { listChanged: false },
-        logging: {},
-      },
-    }
-  );
-
-  // Handle tools/list request
-  server.setRequestHandler(ListToolsRequestSchema, () => {
-    return { tools: TOOL_DEFINITIONS };
-  });
-
-  // Handle tools/call request
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { name, arguments: args } = request.params;
-
-    try {
-      let result: unknown;
-
-      switch (name) {
-        case 'memory_load': {
-          const input = MemoryLoadInputSchema.parse(args ?? {});
-          result = await memoryService.memoryLoad(input);
-          break;
-        }
-
-        case 'memory_update': {
-          const input = MemoryUpdateInputV2Schema.parse(args ?? {});
-          result = await memoryService.memoryUpdate(input);
-          break;
-        }
-
-        default:
-          throw new ServiceError(
-            `Unknown tool: ${name}`,
-            ErrorCode.METHOD_NOT_FOUND
-          );
-      }
-
-      return {
-        content: [
-          {
-            type: 'text' as const,
-            text: JSON.stringify(result, null, 2),
-          },
-        ],
-      };
-    } catch (error) {
-      if (error instanceof ServiceError) {
-        return {
-          content: [
-            {
-              type: 'text' as const,
-              text: JSON.stringify({ error: error.message }, null, 2),
-            },
-          ],
-          isError: true,
-        };
-      }
-
-      if (error instanceof Error && error.name === 'ZodError') {
-        return {
-          content: [
-            {
-              type: 'text' as const,
-              text: JSON.stringify({ error: `Invalid parameters: ${error.message}` }, null, 2),
-            },
-          ],
-          isError: true,
-        };
-      }
-
-      // Re-throw for SDK error handling
-      throw error;
-    }
-  });
-
-  return server;
-}
-
-/**
- * Start the MCP server
- */
-async function main(): Promise<void> {
-  const server = createMcpServer();
-  const transport = new StdioServerTransport();
-
-  await server.connect(transport);
-  console.error('MemHub MCP Server running on stdio');
-}
-
-main().catch((error) => {
-  console.error('Fatal error:', error);
-  process.exit(1);
-});
-
-// Check if this file is being run directly
-const isMain = import.meta.url === `file://${process.argv[1]}` || false;
-if (isMain) {
-  // Defer main() execution to avoid blocking module loading
-  setImmediate(() => {
-    main().catch((error) => {
-      console.error('Fatal error:', error);
-      process.exit(1);
-    });
-  });
+#!/usr/bin/env node
+/**
+ * MCP Server - Model Context Protocol server implementation
+ * Uses @modelcontextprotocol/sdk for protocol handling
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { homedir } from 'os';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { MemoryService, ServiceError } from '../services/memory-service.js';
+import {
+  MemoryLoadInputSchema,
+  MemoryUpdateInputV2Schema,
+} from '../contracts/schemas.js';
+import { TOOL_DEFINITIONS, SERVER_INFO } from '../contracts/mcp.js';
+import { ErrorCode } from '../contracts/types.js';
+
+// Get package version
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+interface PackageJson {
+  version?: string;
+}
+
+// npm package runtime: dist/src/server -> package root
+// test runtime: src/server -> package root
+let packageJsonPath = join(__dirname, '../../../package.json');
+if (!existsSync(packageJsonPath)) {
+  // Fallback for test environment (running from src/)
+  packageJsonPath = join(__dirname, '../../package.json');
+}
+
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8')) as PackageJson;
+
+/**
+ * Resolve storage path with the following priority:
+ * 1. MEMHUB_STORAGE_PATH env var (if set):
+ *    - Absolute path: use as-is
+ *    - Relative path starting with '.': resolve from current working directory
+ * 2. Default: ~/.memhub (user home directory)
+ */
+export function resolveStoragePath(): string {
+  const envPath = process.env.MEMHUB_STORAGE_PATH;
+
+  if (envPath) {
+    // If it's an absolute path, use as-is
+    if (envPath.startsWith('/') || envPath.match(/^[A-Z]:\\/i)) {
+      return envPath;
+    }
+    // Relative path: resolve from current working directory
+    return resolve(process.cwd(), envPath);
+  }
+
+  // Default: ~/.memhub
+  return join(homedir(), '.memhub');
+}
+
+/**
+ * Create McpServer instance using SDK
+ */
+export function createMcpServer(): Server {
+  const storagePath = resolveStoragePath();
+  const vectorSearch = process.env.MEMHUB_VECTOR_SEARCH !== 'false';
+  const memoryService = new MemoryService({ storagePath, vectorSearch });
+
+  // Create server using SDK
+  const server = new Server(
+    {
+      name: SERVER_INFO.name,
+      version: packageJson.version || SERVER_INFO.version,
+    },
+    {
+      capabilities: {
+        tools: { listChanged: false },
+        logging: {},
+      },
+    }
+  );
+
+  // Handle tools/list request
+  server.setRequestHandler(ListToolsRequestSchema, () => {
+    return { tools: TOOL_DEFINITIONS };
+  });
+
+  // Handle tools/call request
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    try {
+      let result: unknown;
+
+      switch (name) {
+        case 'memory_load': {
+          const input = MemoryLoadInputSchema.parse(args ?? {});
+          result = await memoryService.memoryLoad(input);
+          break;
+        }
+
+        case 'memory_update': {
+          const input = MemoryUpdateInputV2Schema.parse(args ?? {});
+          result = await memoryService.memoryUpdate(input);
+          break;
+        }
+
+        default:
+          throw new ServiceError(
+            `Unknown tool: ${name}`,
+            ErrorCode.METHOD_NOT_FOUND
+          );
+      }
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+      };
+    } catch (error) {
+      if (error instanceof ServiceError) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify({ error: error.message }, null, 2),
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      if (error instanceof Error && error.name === 'ZodError') {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify({ error: `Invalid parameters: ${error.message}` }, null, 2),
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      // Re-throw for SDK error handling
+      throw error;
+    }
+  });
+
+  return server;
+}
+
+/**
+ * Start the MCP server
+ */
+async function main(): Promise<void> {
+  const server = createMcpServer();
+  const transport = new StdioServerTransport();
+
+  await server.connect(transport);
+  console.error('MemHub MCP Server running on stdio');
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});
+
+// Check if this file is being run directly
+const isMain = import.meta.url === `file://${process.argv[1]}` || false;
+if (isMain) {
+  // Defer main() execution to avoid blocking module loading
+  setImmediate(() => {
+    main().catch((error) => {
+      console.error('Fatal error:', error);
+      process.exit(1);
+    });
+  });
 }

package/src/services/embedding-service.ts

@@ -1,114 +1,114 @@
-/**
- * Embedding Service - Text embedding using @xenova/transformers
- *
- * Uses the all-MiniLM-L6-v2 model (~23MB, downloaded on first use to ~/.cache/huggingface).
- * Singleton pattern with lazy initialization.
- *
- * Note: Uses dynamic imports to avoid loading native modules (sharp) during tests.
- */
-
-/** ONNX model identifier */
-const MODEL_NAME = 'Xenova/all-MiniLM-L6-v2';
-
-/** Output vector dimension for all-MiniLM-L6-v2 */
-export const VECTOR_DIM = 384;
-
-type FeatureExtractionPipeline = (
-    text: string,
-    options: { pooling: string; normalize: boolean }
-) => Promise<{ data: Float32Array }>;
-
-type TransformersModule = {
-    pipeline: (
-        task: string,
-        model: string,
-        options?: { progress_callback?: null }
-    ) => Promise<unknown>;
-    env: {
-        allowRemoteModels: boolean;
-        allowLocalModels: boolean;
-    };
-};
-
-/**
- * Singleton embedding service backed by a local ONNX model.
- * The model is downloaded once and cached in `~/.cache/huggingface`.
- */
-export class EmbeddingService {
-    private static instance: EmbeddingService | null = null;
-    private extractor: FeatureExtractionPipeline | null = null;
-    private initPromise: Promise<void> | null = null;
-    private transformers: TransformersModule | null = null;
-
-    private constructor() {
-        // Constructor is empty - initialization happens in initialize()
-    }
-
-    static getInstance(): EmbeddingService {
-        if (!EmbeddingService.instance) {
-            EmbeddingService.instance = new EmbeddingService();
-        }
-        return EmbeddingService.instance;
-    }
-
-    /**
-     * Initializes the pipeline (idempotent, safe to call multiple times).
-     */
-    async initialize(): Promise<void> {
-        if (this.extractor) return;
-
-        if (!this.initPromise) {
-            this.initPromise = (async () => {
-                // Dynamic import to avoid loading sharp during tests
-                this.transformers = await import('@xenova/transformers') as TransformersModule;
-                
-                // Configure environment
-                this.transformers.env.allowRemoteModels = true;
-                this.transformers.env.allowLocalModels = true;
-                
-                this.extractor = (await this.transformers.pipeline(
-                    'feature-extraction',
-                    MODEL_NAME
-                )) as FeatureExtractionPipeline;
-            })();
-        }
-
-        await this.initPromise;
-    }
-
-    /**
-     * Embeds `text` into a 384-dimension float vector.
-     *
-     * @param text - The text to embed (title + content recommended)
-     * @returns Normalised float vector of length VECTOR_DIM
-     */
-    async embed(text: string): Promise<number[]> {
-        await this.initialize();
-
-        if (!this.extractor) {
-            throw new Error('EmbeddingService: extractor not initialized');
-        }
-
-        const output = await this.extractor(text, {
-            pooling: 'mean',
-            normalize: true,
-        });
-
-        return Array.from(output.data);
-    }
-
-    /**
-     * Convenience: embed a memory's title and content together.
-     */
-    async embedMemory(title: string, content: string): Promise<number[]> {
-        return this.embed(`${title} ${content}`.trim());
-    }
-
-    /**
-     * Reset the singleton instance.
-     * @internal For testing purposes only. Do not use in production code.
-     */
-    static _reset(): void {
-        EmbeddingService.instance = null;
-    }
-}
+/**
+ * Embedding Service - Text embedding using @xenova/transformers
+ *
+ * Uses the all-MiniLM-L6-v2 model (~23MB, downloaded on first use to ~/.cache/huggingface).
+ * Singleton pattern with lazy initialization.
+ *
+ * Note: Uses dynamic imports to avoid loading native modules (sharp) during tests.
+ */
+
+/** ONNX model identifier */
+const MODEL_NAME = 'Xenova/all-MiniLM-L6-v2';
+
+/** Output vector dimension for all-MiniLM-L6-v2 */
+export const VECTOR_DIM = 384;
+
+type FeatureExtractionPipeline = (
+    text: string,
+    options: { pooling: string; normalize: boolean }
+) => Promise<{ data: Float32Array }>;
+
+type TransformersModule = {
+    pipeline: (
+        task: string,
+        model: string,
+        options?: { progress_callback?: null }
+    ) => Promise<unknown>;
+    env: {
+        allowRemoteModels: boolean;
+        allowLocalModels: boolean;
+    };
+};
+
+/**
+ * Singleton embedding service backed by a local ONNX model.
+ * The model is downloaded once and cached in `~/.cache/huggingface`.
+ */
+export class EmbeddingService {
+    private static instance: EmbeddingService | null = null;
+    private extractor: FeatureExtractionPipeline | null = null;
+    private initPromise: Promise<void> | null = null;
+    private transformers: TransformersModule | null = null;
+
+    private constructor() {
+        // Constructor is empty - initialization happens in initialize()
+    }
+
+    static getInstance(): EmbeddingService {
+        if (!EmbeddingService.instance) {
+            EmbeddingService.instance = new EmbeddingService();
+        }
+        return EmbeddingService.instance;
+    }
+
+    /**
+     * Initializes the pipeline (idempotent, safe to call multiple times).
+     */
+    async initialize(): Promise<void> {
+        if (this.extractor) return;
+
+        if (!this.initPromise) {
+            this.initPromise = (async () => {
+                // Dynamic import to avoid loading sharp during tests
+                this.transformers = await import('@xenova/transformers') as TransformersModule;
+                
+                // Configure environment
+                this.transformers.env.allowRemoteModels = true;
+                this.transformers.env.allowLocalModels = true;
+                
+                this.extractor = (await this.transformers.pipeline(
+                    'feature-extraction',
+                    MODEL_NAME
+                )) as FeatureExtractionPipeline;
+            })();
+        }
+
+        await this.initPromise;
+    }
+
+    /**
+     * Embeds `text` into a 384-dimension float vector.
+     *
+     * @param text - The text to embed (title + content recommended)
+     * @returns Normalised float vector of length VECTOR_DIM
+     */
+    async embed(text: string): Promise<number[]> {
+        await this.initialize();
+
+        if (!this.extractor) {
+            throw new Error('EmbeddingService: extractor not initialized');
+        }
+
+        const output = await this.extractor(text, {
+            pooling: 'mean',
+            normalize: true,
+        });
+
+        return Array.from(output.data);
+    }
+
+    /**
+     * Convenience: embed a memory's title and content together.
+     */
+    async embedMemory(title: string, content: string): Promise<number[]> {
+        return this.embed(`${title} ${content}`.trim());
+    }
+
+    /**
+     * Reset the singleton instance.
+     * @internal For testing purposes only. Do not use in production code.
+     */
+    static _reset(): void {
+        EmbeddingService.instance = null;
+    }
+}

package/src/services/index.ts

@@ -1,5 +1,5 @@
-/**
- * Services exports
- */
-
-export * from './memory-service.js';
+/**
+ * Services exports
+ */
+
+export * from './memory-service.js';