@synth-coder/memhub 0.2.2 → 0.2.4

package/src/contracts/types.ts

@@ -25,10 +25,10 @@ export type Slug = string;
  * Content is split between YAML Front Matter (metadata) and Markdown body
  */
 export type MemoryEntryType =
-  | '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
 
 export interface Memory {
   /** UUID v4 unique identifier */

package/src/server/mcp-server.ts

@@ -5,19 +5,14 @@
  */
 
 import { readFileSync, existsSync } from 'fs';
-import { join, dirname } from 'path';
+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 { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { MemoryService, ServiceError } from '../services/memory-service.js';
-import {
-  MemoryLoadInputSchema,
-  MemoryUpdateInputV2Schema,
-} from '../contracts/schemas.js';
+import { MemoryLoadInputSchema, MemoryUpdateInputV2Schema } from '../contracts/schemas.js';
 import { TOOL_DEFINITIONS, SERVER_INFO } from '../contracts/mcp.js';
 import { ErrorCode } from '../contracts/types.js';
 
@@ -38,11 +33,34 @@ if (!existsSync(packageJsonPath)) {
 
 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 = process.env.MEMHUB_STORAGE_PATH || './memories';
+  const storagePath = resolveStoragePath();
   const vectorSearch = process.env.MEMHUB_VECTOR_SEARCH !== 'false';
   const memoryService = new MemoryService({ storagePath, vectorSearch });
 
@@ -66,7 +84,7 @@ export function createMcpServer(): Server {
   });
 
   // Handle tools/call request
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  server.setRequestHandler(CallToolRequestSchema, async request => {
     const { name, arguments: args } = request.params;
 
     try {
@@ -86,10 +104,7 @@ export function createMcpServer(): Server {
         }
 
         default:
-          throw new ServiceError(
-            `Unknown tool: ${name}`,
-            ErrorCode.METHOD_NOT_FOUND
-          );
+          throw new ServiceError(`Unknown tool: ${name}`, ErrorCode.METHOD_NOT_FOUND);
       }
 
       return {
@@ -134,7 +149,7 @@ export function createMcpServer(): Server {
 }
 
 /**
- * Start the MCP server
+ * Start the MCP server (only when run directly)
  */
 async function main(): Promise<void> {
   const server = createMcpServer();
@@ -144,19 +159,11 @@ async function main(): Promise<void> {
   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
+// Only run main() when this file is executed 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);
-    });
+  main().catch(error => {
+    console.error('Fatal error:', error);
+    process.exit(1);
   });
-}
+}

package/src/services/embedding-service.ts

@@ -14,20 +14,20 @@ const MODEL_NAME = 'Xenova/all-MiniLM-L6-v2';
 export const VECTOR_DIM = 384;
 
 type FeatureExtractionPipeline = (
-    text: string,
-    options: { pooling: string; normalize: boolean }
+  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;
-    };
+  pipeline: (
+    task: string,
+    model: string,
+    options?: { progress_callback?: null }
+  ) => Promise<unknown>;
+  env: {
+    allowRemoteModels: boolean;
+    allowLocalModels: boolean;
+  };
 };
 
 /**
@@ -35,80 +35,80 @@ type TransformersModule = {
  * 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()
+  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();
     }
-
-    static getInstance(): EmbeddingService {
-        if (!EmbeddingService.instance) {
-            EmbeddingService.instance = new EmbeddingService();
-        }
-        return EmbeddingService.instance;
+    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;
+      })();
     }
 
-    /**
-     * 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;
-    }
+    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);
-    }
+  /**
+   * 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();
 
-    /**
-     * Convenience: embed a memory's title and content together.
-     */
-    async embedMemory(title: string, content: string): Promise<number[]> {
-        return this.embed(`${title} ${content}`.trim());
+    if (!this.extractor) {
+      throw new Error('EmbeddingService: extractor not initialized');
     }
 
-    /**
-     * Reset the singleton instance.
-     * @internal For testing purposes only. Do not use in production code.
-     */
-    static _reset(): void {
-        EmbeddingService.instance = null;
-    }
+    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/memory-service.ts

@@ -23,6 +23,9 @@ import type {
 } from '../contracts/types.js';
 import { ErrorCode } from '../contracts/types.js';
 import { MarkdownStorage, StorageError } from '../storage/markdown-storage.js';
+import lockfile from 'proper-lockfile';
+
+const LOCK_TIMEOUT = 5000; // 5 seconds
 
 /** Minimal interface required from VectorIndex (avoids static import of native module) */
 interface IVectorIndex {
@@ -68,12 +71,14 @@ export interface MemoryServiceConfig {
  * Memory service implementation
  */
 export class MemoryService {
+  private readonly storagePath: string;
   private readonly storage: MarkdownStorage;
   private readonly vectorIndex: IVectorIndex | null;
   private readonly embedding: IEmbeddingService | null;
   private readonly vectorSearchEnabled: boolean;
 
   constructor(config: MemoryServiceConfig) {
+    this.storagePath = config.storagePath;
     this.storage = new MarkdownStorage({ storagePath: config.storagePath });
     this.vectorSearchEnabled = config.vectorSearch !== false;
 
@@ -101,7 +106,7 @@ export class MemoryService {
           await initPromise;
           return resolvedVectorIndex!.upsert(memory, vector);
         },
-        delete: async (id) => {
+        delete: async id => {
           await initPromise;
           return resolvedVectorIndex!.delete(id);
         },
@@ -116,7 +121,7 @@ export class MemoryService {
           await initPromise;
           return resolvedEmbedding!.embedMemory(title, content);
         },
-        embed: async (text) => {
+        embed: async text => {
           await initPromise;
           return resolvedEmbedding!.embed(text);
         },
@@ -172,29 +177,36 @@ export class MemoryService {
    * Creates a new memory entry
    */
   async create(input: CreateMemoryInput): Promise<CreateResult> {
-    const now = new Date().toISOString();
-    const id = randomUUID();
-
-    const memory: Memory = {
-      id,
-      createdAt: now,
-      updatedAt: now,
-      tags: input.tags ?? [],
-      category: input.category ?? 'general',
-      importance: input.importance ?? 3,
-      title: input.title,
-      content: input.content,
-    };
-
+    const release = await lockfile.lock(this.storagePath, {
+      retries: { retries: 100, minTimeout: 50, maxTimeout: LOCK_TIMEOUT / 100 },
+    });
     try {
-      const filePath = await this.storage.write(memory);
-      this.scheduleVectorUpsert(memory);
-      return { id, filePath, memory };
-    } catch (error) {
-      throw new ServiceError(
-        `Failed to create memory: ${error instanceof Error ? error.message : 'Unknown error'}`,
-        ErrorCode.STORAGE_ERROR
-      );
+      const now = new Date().toISOString();
+      const id = randomUUID();
+
+      const memory: Memory = {
+        id,
+        createdAt: now,
+        updatedAt: now,
+        tags: input.tags ?? [],
+        category: input.category ?? 'general',
+        importance: input.importance ?? 3,
+        title: input.title,
+        content: input.content,
+      };
+
+      try {
+        const filePath = await this.storage.write(memory);
+        this.scheduleVectorUpsert(memory);
+        return { id, filePath, memory };
+      } catch (error) {
+        throw new ServiceError(
+          `Failed to create memory: ${error instanceof Error ? error.message : 'Unknown error'}`,
+          ErrorCode.STORAGE_ERROR
+        );
+      }
+    } finally {
+      await release();
     }
   }
 
@@ -220,38 +232,45 @@ export class MemoryService {
    * Updates an existing memory
    */
   async update(input: UpdateMemoryInput): Promise<UpdateResult> {
-    let existing: Memory;
+    const release = await lockfile.lock(this.storagePath, {
+      retries: { retries: 100, minTimeout: 50, maxTimeout: LOCK_TIMEOUT / 100 },
+    });
     try {
-      existing = await this.storage.read(input.id);
-    } catch (error) {
-      if (error instanceof StorageError && error.message.includes('not found')) {
-        throw new ServiceError(`Memory not found: ${input.id}`, ErrorCode.NOT_FOUND);
+      let existing: Memory;
+      try {
+        existing = await this.storage.read(input.id);
+      } catch (error) {
+        if (error instanceof StorageError && error.message.includes('not found')) {
+          throw new ServiceError(`Memory not found: ${input.id}`, ErrorCode.NOT_FOUND);
+        }
+        throw new ServiceError(
+          `Failed to read memory for update: ${error instanceof Error ? error.message : 'Unknown error'}`,
+          ErrorCode.STORAGE_ERROR
+        );
       }
-      throw new ServiceError(
-        `Failed to read memory for update: ${error instanceof Error ? error.message : 'Unknown error'}`,
-        ErrorCode.STORAGE_ERROR
-      );
-    }
 
-    const updated: Memory = {
-      ...existing,
-      updatedAt: new Date().toISOString(),
-      ...(input.title !== undefined && { title: input.title }),
-      ...(input.content !== undefined && { content: input.content }),
-      ...(input.tags !== undefined && { tags: input.tags }),
-      ...(input.category !== undefined && { category: input.category }),
-      ...(input.importance !== undefined && { importance: input.importance }),
-    };
+      const updated: Memory = {
+        ...existing,
+        updatedAt: new Date().toISOString(),
+        ...(input.title !== undefined && { title: input.title }),
+        ...(input.content !== undefined && { content: input.content }),
+        ...(input.tags !== undefined && { tags: input.tags }),
+        ...(input.category !== undefined && { category: input.category }),
+        ...(input.importance !== undefined && { importance: input.importance }),
+      };
 
-    try {
-      await this.storage.write(updated);
-      this.scheduleVectorUpsert(updated);
-      return { memory: updated };
-    } catch (error) {
-      throw new ServiceError(
-        `Failed to update memory: ${error instanceof Error ? error.message : 'Unknown error'}`,
-        ErrorCode.STORAGE_ERROR
-      );
+      try {
+        await this.storage.write(updated);
+        this.scheduleVectorUpsert(updated);
+        return { memory: updated };
+      } catch (error) {
+        throw new ServiceError(
+          `Failed to update memory: ${error instanceof Error ? error.message : 'Unknown error'}`,
+          ErrorCode.STORAGE_ERROR
+        );
+      }
+    } finally {
+      await release();
     }
   }
 
@@ -259,6 +278,9 @@ export class MemoryService {
    * Deletes a memory by ID
    */
   async delete(input: DeleteMemoryInput): Promise<DeleteResult> {
+    const release = await lockfile.lock(this.storagePath, {
+      retries: { retries: 100, minTimeout: 50, maxTimeout: LOCK_TIMEOUT / 100 },
+    });
     try {
       const filePath = await this.storage.delete(input.id);
       await this.removeFromVectorIndex(input.id);
@@ -271,6 +293,8 @@ export class MemoryService {
         `Failed to delete memory: ${error instanceof Error ? error.message : 'Unknown error'}`,
         ErrorCode.STORAGE_ERROR
       );
+    } finally {
+      await release();
     }
   }
 
@@ -288,9 +312,7 @@ export class MemoryService {
       let memories: Memory[] = [];
       for (const file of files) {
         try {
-          const memory = await this.storage.read(
-            this.extractIdFromContent(file.content)
-          );
+          const memory = await this.storage.read(this.extractIdFromContent(file.content));
           memories.push(memory);
         } catch {
           continue;
@@ -301,9 +323,7 @@ export class MemoryService {
         memories = memories.filter(m => m.category === input.category);
       }
       if (input.tags && input.tags.length > 0) {
-        memories = memories.filter(m =>
-          input.tags!.every(tag => m.tags.includes(tag))
-        );
+        memories = memories.filter(m => input.tags!.every(tag => m.tags.includes(tag)));
       }
       if (input.fromDate) {
         memories = memories.filter(m => m.createdAt >= input.fromDate!);
@@ -361,10 +381,7 @@ export class MemoryService {
     if (this.vectorSearchEnabled && this.vectorIndex && this.embedding) {
       try {
         const queryVec = await this.embedding.embed(input.query);
-        const vectorResults = await this.vectorIndex.search(
-          queryVec,
-          input.limit ?? 10
-        );
+        const vectorResults = await this.vectorIndex.search(queryVec, input.limit ?? 10);
 
         const results: SearchResult[] = [];
         for (const vr of vectorResults) {
@@ -514,63 +531,81 @@ export class MemoryService {
    * memory_update — unified write API (append/upsert)
    */
   async memoryUpdate(input: MemoryUpdateInput): Promise<MemoryUpdateOutput> {
-    const now = new Date().toISOString();
-    const sessionId = input.sessionId ?? randomUUID();
+    const release = await lockfile.lock(this.storagePath, {
+      retries: { retries: 100, minTimeout: 50, maxTimeout: LOCK_TIMEOUT / 100 },
+    });
+    try {
+      const now = new Date().toISOString();
+      const sessionId = input.sessionId ?? randomUUID();
 
-    if (input.id) {
-      const updatedResult = await this.update({
-        id: input.id,
-        title: input.title,
-        content: input.content,
-        tags: input.tags,
-        category: input.category,
-        importance: input.importance,
-      });
+      if (input.id) {
+        // Inline update logic to avoid nested lock
+        let existing: Memory;
+        try {
+          existing = await this.storage.read(input.id);
+        } catch (error) {
+          if (error instanceof StorageError && error.message.includes('not found')) {
+            throw new ServiceError(`Memory not found: ${input.id}`, ErrorCode.NOT_FOUND);
+          }
+          throw new ServiceError(
+            `Failed to read memory for update: ${error instanceof Error ? error.message : 'Unknown error'}`,
+            ErrorCode.STORAGE_ERROR
+          );
+        }
+
+        const updatedMemory: Memory = {
+          ...existing,
+          updatedAt: now,
+          sessionId,
+          entryType: input.entryType,
+          ...(input.title !== undefined && { title: input.title }),
+          ...(input.content !== undefined && { content: input.content }),
+          ...(input.tags !== undefined && { tags: input.tags }),
+          ...(input.category !== undefined && { category: input.category }),
+          ...(input.importance !== undefined && { importance: input.importance }),
+        };
+
+        const filePath = await this.storage.write(updatedMemory);
+        this.scheduleVectorUpsert(updatedMemory);
+
+        return {
+          id: updatedMemory.id,
+          sessionId,
+          filePath,
+          created: false,
+          updated: true,
+          memory: updatedMemory,
+        };
+      }
 
-      const updatedMemory: Memory = {
-        ...updatedResult.memory,
+      const id = randomUUID();
+      const createdMemory: Memory = {
+        id,
+        createdAt: now,
+        updatedAt: now,
         sessionId,
         entryType: input.entryType,
+        tags: input.tags ?? [],
+        category: input.category ?? 'general',
+        importance: input.importance ?? 3,
+        title: input.title ?? 'memory note',
+        content: input.content,
       };
 
-      const filePath = await this.storage.write(updatedMemory);
-      this.scheduleVectorUpsert(updatedMemory);
+      const filePath = await this.storage.write(createdMemory);
+      this.scheduleVectorUpsert(createdMemory);
 
       return {
-        id: updatedMemory.id,
+        id,
         sessionId,
         filePath,
-        created: false,
-        updated: true,
-        memory: updatedMemory,
+        created: true,
+        updated: false,
+        memory: createdMemory,
       };
+    } finally {
+      await release();
     }
-
-    const id = randomUUID();
-    const createdMemory: Memory = {
-      id,
-      createdAt: now,
-      updatedAt: now,
-      sessionId,
-      entryType: input.entryType,
-      tags: input.tags ?? [],
-      category: input.category ?? 'general',
-      importance: input.importance ?? 3,
-      title: input.title ?? 'memory note',
-      content: input.content,
-    };
-
-    const filePath = await this.storage.write(createdMemory);
-    this.scheduleVectorUpsert(createdMemory);
-
-    return {
-      id,
-      sessionId,
-      filePath,
-      created: true,
-      updated: false,
-      memory: createdMemory,
-    };
   }
 
   // ---------------------------------------------------------------------------

package/src/storage/markdown-storage.ts

@@ -2,15 +2,7 @@
  * Markdown Storage - Handles file system operations for memory storage
  */
 
-import {
-  readFile,
-  writeFile,
-  unlink,
-  readdir,
-  stat,
-  access,
-  mkdir,
-} from 'fs/promises';
+import { readFile, writeFile, unlink, readdir, stat, access, mkdir } from 'fs/promises';
 import { join, extname } from 'path';
 import { constants } from 'fs';
 import type { Memory, MemoryFile } from '../contracts/types.js';