@synth-coder/memhub 0.1.5 → 0.2.0

package/dist/src/storage/vector-index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * VectorIndex - LanceDB-backed vector search index for memories.
+ *
+ * This is a search cache only. Markdown files remain the source of truth.
+ * The index can be rebuilt from Markdown files at any time.
+ */
+import type { Memory } from '../contracts/types.js';
+/**
+ * Row stored in the LanceDB table.
+ * The `vector` field is the only one required by LanceDB; all others are metadata filters.
+ */
+export interface VectorRow {
+    id: string;
+    vector: number[];
+    title: string;
+    category: string;
+    tags: string;
+    importance: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface VectorSearchResult {
+    id: string;
+    /** Cosine distance (lower = more similar). Converted to 0-1 score by caller. */
+    _distance: number;
+}
+/**
+ * LanceDB vector index wrapper.
+ * Data lives at `{storagePath}/.lancedb/`.
+ */
+export declare class VectorIndex {
+    private readonly dbPath;
+    private db;
+    private table;
+    private initPromise;
+    constructor(storagePath: string);
+    /** Idempotent initialisation — safe to call multiple times. */
+    initialize(): Promise<void>;
+    private _init;
+    /**
+     * Upserts a memory row into the index.
+     * LanceDB doesn't have a native upsert so we delete-then-add.
+     */
+    upsert(memory: Memory, vector: number[]): Promise<void>;
+    /**
+     * Removes a memory from the index by ID.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Searches for the nearest neighbours to `vector`.
+     *
+     * @param vector - Query embedding (must be 384-dim)
+     * @param limit  - Max results to return
+     * @returns Array ordered by ascending distance (most similar first)
+     */
+    search(vector: number[], limit?: number): Promise<VectorSearchResult[]>;
+    /**
+     * Returns the number of rows in the index.
+     */
+    count(): Promise<number>;
+}
+//# sourceMappingURL=vector-index.d.ts.map

package/dist/src/storage/vector-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-index.d.ts","sourceRoot":"","sources":["../../../src/storage/vector-index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AASpD;;;GAGG;AACH,MAAM,WAAW,SAAS;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,qBAAa,WAAW;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,EAAE,CAAmC;IAC7C,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,WAAW,CAA8B;gBAErC,WAAW,EAAE,MAAM;IAI/B,+DAA+D;IACzD,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;YASnB,KAAK;IAgCnB;;;OAGG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB7D;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvC;;;;;;OAMG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAczE;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;CAIjC"}

package/dist/src/storage/vector-index.js

@@ -0,0 +1,123 @@
+/**
+ * VectorIndex - LanceDB-backed vector search index for memories.
+ *
+ * This is a search cache only. Markdown files remain the source of truth.
+ * The index can be rebuilt from Markdown files at any time.
+ */
+import * as lancedb from '@lancedb/lancedb';
+import { mkdir, access } from 'fs/promises';
+import { join } from 'path';
+import { constants } from 'fs';
+const TABLE_NAME = 'memories';
+/** Escape single quotes in id strings to prevent SQL injection */
+function escapeId(id) {
+    return id.replace(/'/g, "''");
+}
+/**
+ * LanceDB vector index wrapper.
+ * Data lives at `{storagePath}/.lancedb/`.
+ */
+export class VectorIndex {
+    dbPath;
+    db = null;
+    table = null;
+    initPromise = null;
+    constructor(storagePath) {
+        this.dbPath = join(storagePath, '.lancedb');
+    }
+    /** Idempotent initialisation — safe to call multiple times. */
+    async initialize() {
+        if (this.table)
+            return;
+        if (!this.initPromise) {
+            this.initPromise = this._init();
+        }
+        await this.initPromise;
+    }
+    async _init() {
+        // Ensure the directory exists
+        try {
+            await access(this.dbPath, constants.F_OK);
+        }
+        catch {
+            await mkdir(this.dbPath, { recursive: true });
+        }
+        this.db = await lancedb.connect(this.dbPath);
+        const existingTables = await this.db.tableNames();
+        if (existingTables.includes(TABLE_NAME)) {
+            this.table = await this.db.openTable(TABLE_NAME);
+        }
+        else {
+            // Create table with a dummy row so schema is established, then delete it
+            const dummy = {
+                id: '__init__',
+                vector: new Array(384).fill(0),
+                title: '',
+                category: '',
+                tags: '[]',
+                importance: 0,
+                createdAt: '',
+                updatedAt: '',
+            };
+            // LanceDB expects Record<string, unknown>[] but our VectorRow is typed more strictly
+            // Cast is safe here as VectorRow is a subset of Record<string, unknown>
+            this.table = await this.db.createTable(TABLE_NAME, [dummy]);
+            await this.table.delete(`id = '__init__'`);
+        }
+    }
+    /**
+     * Upserts a memory row into the index.
+     * LanceDB doesn't have a native upsert so we delete-then-add.
+     */
+    async upsert(memory, vector) {
+        await this.initialize();
+        const table = this.table;
+        // Remove existing row (if any)
+        await table.delete(`id = '${escapeId(memory.id)}'`);
+        const row = {
+            id: memory.id,
+            vector,
+            title: memory.title,
+            category: memory.category,
+            tags: JSON.stringify(memory.tags),
+            importance: memory.importance,
+            createdAt: memory.createdAt,
+            updatedAt: memory.updatedAt,
+        };
+        // LanceDB expects Record<string, unknown>[] but our VectorRow is typed more strictly
+        await table.add([row]);
+    }
+    /**
+     * Removes a memory from the index by ID.
+     */
+    async delete(id) {
+        await this.initialize();
+        await this.table.delete(`id = '${escapeId(id)}'`);
+    }
+    /**
+     * Searches for the nearest neighbours to `vector`.
+     *
+     * @param vector - Query embedding (must be 384-dim)
+     * @param limit  - Max results to return
+     * @returns Array ordered by ascending distance (most similar first)
+     */
+    async search(vector, limit = 10) {
+        await this.initialize();
+        const results = await this.table
+            .vectorSearch(vector)
+            .limit(limit)
+            .toArray();
+        return results.map((row) => ({
+            id: row['id'],
+            _distance: row['_distance'],
+        }));
+    }
+    /**
+     * Returns the number of rows in the index.
+     */
+    async count() {
+        await this.initialize();
+        return this.table.countRows();
+    }
+}
+//# sourceMappingURL=vector-index.js.map

package/dist/src/storage/vector-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-index.js","sourceRoot":"","sources":["../../../src/storage/vector-index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synth-coder/memhub",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "A Git-friendly memory hub using Markdown-based storage with YAML Front Matter",
   "type": "module",
   "main": "dist/src/index.js",
@@ -32,21 +32,24 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
+    "@lancedb/lancedb": "^0.26.2",
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "yaml": "^2.3.4",
-    "zod": "^3.22.4"
+    "@xenova/transformers": "^2.17.2",
+    "sharp": "^0.34.5",
+    "yaml": "^2.8.2",
+    "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@types/node": "^20.10.0",
-    "@typescript-eslint/eslint-plugin": "^6.15.0",
-    "@typescript-eslint/parser": "^6.15.0",
-    "@vitest/coverage-v8": "^1.1.0",
-    "eslint": "^8.56.0",
-    "eslint-config-prettier": "^9.1.0",
-    "eslint-plugin-import": "^2.29.1",
-    "prettier": "^3.1.1",
-    "typescript": "^5.3.3",
-    "vitest": "^1.1.0"
+    "@types/node": "^20.19.35",
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "@typescript-eslint/parser": "^6.21.0",
+    "@vitest/coverage-v8": "^1.6.1",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^9.1.2",
+    "eslint-plugin-import": "^2.32.0",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3",
+    "vitest": "^1.6.1"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/contracts/mcp.ts

@@ -15,7 +15,7 @@ export const MCP_PROTOCOL_VERSION = '2024-11-05';
 /** Server information */
 export const SERVER_INFO = {
   name: 'memhub',
-  version: '0.1.0',
+  version: '0.2.0',
 } as const;
 
 // ============================================================================
@@ -51,25 +51,47 @@ export type ToolName = (typeof TOOL_NAMES)[number];
 export const TOOL_DEFINITIONS: readonly Tool[] = [
   {
     name: 'memory_load',
-    description:
-      'STM first step. Call at the first turn after receiving user prompt to load short-term memory context for this session/task.',
+    description: `Retrieve stored memories to recall user preferences, past decisions, project context, and learned knowledge.
+
+WHEN TO USE (call proactively):
+• Starting a new conversation or task
+• User references past discussions ("remember when...", "as I mentioned before")
+• Need context about user's coding style, preferences, or project decisions
+• Uncertain about user's existing preferences or constraints
+• Before making assumptions about user requirements
+
+WHAT IT PROVIDES:
+• User preferences (coding style, frameworks, naming conventions)
+• Past decisions and their rationale
+• Project-specific context and constraints
+• Previously learned knowledge about the user
+
+Call this early to provide personalized, context-aware responses.`,
     inputSchema: {
       type: 'object',
       properties: {
-        id: { type: 'string', description: 'Optional memory id for direct fetch' },
-        sessionId: {
+        query: {
           type: 'string',
-          description: 'Optional session UUID to load current CLI/task context',
+          description:
+            'Search query to find relevant memories. Examples: "react preferences", "error handling approach", "database choice"',
         },
-        date: { type: 'string', description: 'Optional date filter (YYYY-MM-DD)' },
-        query: { type: 'string', description: 'Optional text query for relevant context' },
-        category: { type: 'string' },
-        tags: { type: 'array', items: { type: 'string' } },
-        limit: { type: 'number', description: 'Max results, default 20' },
-        scope: {
+        id: {
           type: 'string',
-          enum: ['stm', 'all'],
-          description: 'stm for short-term context window; all for broader retrieval',
+          description: 'Direct lookup by memory ID (if known)',
+        },
+        category: {
+          type: 'string',
+          description:
+            'Filter by category: "general" (default), "preference", "decision", "knowledge", "project"',
+        },
+        tags: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Filter by tags. Example: ["typescript", "backend"]',
+        },
+        limit: {
+          type: 'number',
+          description: 'Max results (default: 20, max: 100)',
         },
       },
       additionalProperties: false,
@@ -77,23 +99,59 @@ export const TOOL_DEFINITIONS: readonly Tool[] = [
   },
   {
     name: 'memory_update',
-    description:
-      'STM write-back step. Call at the final turn to append/upsert new decisions, preferences, task-state changes, and key outputs.',
+    description: `Store important information to remember for future conversations.
+
+WHEN TO USE (call when learning something worth remembering):
+• User explicitly states a preference ("I prefer functional components")
+• User makes a decision with rationale ("We'll use PostgreSQL because...")
+• You discover important project context (tech stack, constraints, patterns)
+• User corrects your assumption ("Actually, I don't use Redux")
+• Task state changes that should persist
+
+WHAT TO STORE:
+• Preferences: coding style, frameworks, naming conventions
+• Decisions: architecture choices, library selections, with reasoning
+• Knowledge: project-specific patterns, gotchas, conventions
+• Context: team structure, deployment process, testing approach
+
+TIPS:
+• content is required and most important
+• title helps with search (auto-generated if omitted)
+• Use entryType to categorize: "preference", "decision", "context", "fact"
+• importance: 1-5 (default: 3), higher = more critical to remember`,
     inputSchema: {
       type: 'object',
       properties: {
-        id: { type: 'string', description: 'Optional id. Present = update existing record' },
-        sessionId: { type: 'string', description: 'Session UUID. Auto-created if omitted' },
-        mode: { type: 'string', enum: ['append', 'upsert'], description: 'Default append' },
+        content: {
+          type: 'string',
+          description:
+            'The information to remember. Be specific and include context. Example: "User prefers TypeScript with strict mode. Uses functional React components with hooks. Avoids class components."',
+        },
+        title: {
+          type: 'string',
+          description:
+            'Brief title for the memory (auto-generated from content if omitted). Example: "TypeScript and React preferences"',
+        },
         entryType: {
           type: 'string',
-          enum: ['decision', 'preference', 'knowledge', 'todo', 'state_change'],
+          enum: ['preference', 'decision', 'context', 'fact'],
+          description:
+            'Type of memory. "preference" for user likes/dislikes, "decision" for choices made, "context" for project info, "fact" for learned facts',
+        },
+        category: {
+          type: 'string',
+          description:
+            'Category for grouping. Default: "general". Example: "frontend", "backend", "project-alpha"',
+        },
+        tags: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Tags for filtering. Example: ["typescript", "react", "coding-style"]',
+        },
+        importance: {
+          type: 'number',
+          description: 'Importance level 1-5. 5 = critical, always recall. Default: 3',
         },
-        title: { type: 'string', description: 'Optional title' },
-        content: { type: 'string', description: 'Required memory body' },
-        tags: { type: 'array', items: { type: 'string' } },
-        category: { type: 'string' },
-        importance: { type: 'number' },
       },
       required: ['content'],
       additionalProperties: false,
@@ -145,20 +203,17 @@ export type ToolResult<T extends ToolName> = T extends 'memory_load'
 export type ToolInput<T extends ToolName> = T extends 'memory_load'
   ? {
       id?: string;
-      sessionId?: string;
-      date?: string;
       query?: string;
       category?: string;
       tags?: string[];
       limit?: number;
-      scope?: 'stm' | 'all';
     }
   : T extends 'memory_update'
     ? {
         id?: string;
         sessionId?: string;
         mode?: 'append' | 'upsert';
-        entryType?: 'decision' | 'preference' | 'knowledge' | 'todo' | 'state_change';
+        entryType?: 'preference' | 'decision' | 'context' | 'fact';
         title?: string;
         content: string;
         tags?: string[];

package/src/contracts/schemas.ts

@@ -41,11 +41,10 @@ export const ImportanceSchema = z.number().int().min(1).max(5);
 
 /** STM memory entry type */
 export const MemoryEntryTypeSchema = z.enum([
-  'decision',
-  'preference',
-  'knowledge',
-  'todo',
-  'state_change',
+  'preference',  // User likes/dislikes
+  'decision',    // Technical choices with reasoning
+  'context',     // Project/environment information
+  'fact',        // Objective knowledge
 ]);
 
 // ============================================================================
@@ -208,13 +207,10 @@ export const SearchMemoryInputSchema = z.object({
 /** memory_load input schema */
 export const MemoryLoadInputSchema = z.object({
   id: UUIDSchema.optional(),
-  sessionId: UUIDSchema.optional(),
-  date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
   query: z.string().min(1).max(1000).optional(),
   category: CategorySchema.optional(),
   tags: z.array(TagSchema).optional(),
   limit: z.number().int().min(1).max(100).optional(),
-  scope: z.enum(['stm', 'all']).optional(),
 });
 
 /** memory_update (upsert/append) input schema */

package/src/contracts/types.ts

@@ -25,11 +25,10 @@ export type Slug = string;
  * Content is split between YAML Front Matter (metadata) and Markdown body
  */
 export type MemoryEntryType =
-  | 'decision'
-  | 'preference'
-  | 'knowledge'
-  | 'todo'
-  | 'state_change';
+  | 'preference'  // User likes/dislikes
+  | 'decision'    // Technical choices with reasoning
+  | 'context'     // Project/environment information
+  | 'fact';       // Objective knowledge
 
 export interface Memory {
   /** UUID v4 unique identifier */
@@ -249,11 +248,8 @@ export interface SearchMemoryInput extends Partial<MemoryFilter> {
  */
 export interface MemoryLoadInput extends Partial<MemoryFilter> {
   readonly id?: UUID;
-  readonly sessionId?: UUID;
-  readonly date?: string;
   readonly query?: string;
   readonly limit?: number;
-  readonly scope?: 'stm' | 'all';
 }
 
 /**

package/src/server/mcp-server.ts

@@ -4,10 +4,9 @@
  * Uses @modelcontextprotocol/sdk for protocol handling
  */
 
-import { readFileSync } from 'fs';
+import { readFileSync, existsSync } from 'fs';
 import { join, dirname } 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 {
@@ -30,7 +29,12 @@ interface PackageJson {
 }
 
 // npm package runtime: dist/src/server -> package root
-const packageJsonPath = join(__dirname, '../../../package.json');
+// 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;
 
@@ -38,9 +42,9 @@ const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8')) as Packag
  * Create McpServer instance using SDK
  */
 export function createMcpServer(): Server {
-  const defaultStoragePath = join(homedir(), '.memhub');
-  const storagePath = process.env.MEMHUB_STORAGE_PATH || defaultStoragePath;
-  const memoryService = new MemoryService({ storagePath });
+  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(
@@ -143,4 +147,16 @@ async function main(): Promise<void> {
 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

@@ -0,0 +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;
+    }
+}