@synth-coder/memhub 0.1.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@synth-coder/memhub",
+  "version": "0.1.0",
+  "description": "A Git-friendly memory hub using Markdown-based storage with YAML Front Matter",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "memhub": "dist/server/mcp-server.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src test --ext .ts",
+    "lint:fix": "eslint src test --ext .ts --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\" \"docs/**/*.md\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\" \"docs/**/*.md\"",
+    "typecheck": "tsc --noEmit --project tsconfig.json",
+    "quality": "npm run lint && npm run typecheck && npm run test:coverage",
+    "ci": "npm run quality"
+  },
+  "keywords": [
+    "mcp",
+    "memory",
+    "markdown",
+    "yaml",
+    "git-friendly"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "zod": "^3.22.4",
+    "yaml": "^2.3.4"
+  },
+  "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"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/contracts/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Contract exports - Central export point for all types and schemas
+ */
+
+// Types
+export * from './types.js';
+
+// Schemas
+export * from './schemas.js';
+
+// MCP protocol types
+export * from './mcp.js';

package/src/contracts/mcp.ts

@@ -0,0 +1,303 @@
+/**
+ * MCP (Model Context Protocol) specific types and constants
+ * Defines the protocol structures for stdio-based communication
+ */
+
+import type { Memory } from './types.js';
+
+// ============================================================================
+// MCP Protocol Version
+// ============================================================================
+
+/** Current MCP protocol version */
+export const MCP_PROTOCOL_VERSION = '2024-11-05';
+
+/** Server information */
+export const SERVER_INFO = {
+  name: 'memhub',
+  version: '0.1.0',
+} as const;
+
+// ============================================================================
+// MCP Request/Response Types
+// ============================================================================
+
+/** JSON-RPC request ID */
+export type RequestId = string | number;
+
+/** Base JSON-RPC request structure */
+export interface JsonRpcRequest<T = unknown> {
+  jsonrpc: '2.0';
+  id?: RequestId;
+  method: string;
+  params?: T;
+}
+
+/** Base JSON-RPC response structure */
+export interface JsonRpcResponse<T = unknown> {
+  jsonrpc: '2.0';
+  id: RequestId | null;
+  result?: T;
+  error?: JsonRpcError;
+}
+
+/** JSON-RPC error structure */
+export interface JsonRpcError {
+  code: number;
+  message: string;
+  data?: unknown;
+}
+
+/** JSON-RPC notification (no response expected) */
+export interface JsonRpcNotification<T = unknown> {
+  jsonrpc: '2.0';
+  method: string;
+  params?: T;
+}
+
+// ============================================================================
+// MCP Lifecycle Messages
+// ============================================================================
+
+/** Initialize request parameters */
+export interface InitializeParams {
+  protocolVersion: string;
+  capabilities: ClientCapabilities;
+  clientInfo: Implementation;
+}
+
+/** Initialize result */
+export interface InitializeResult {
+  protocolVersion: string;
+  capabilities: ServerCapabilities;
+  serverInfo: Implementation;
+}
+
+/** Implementation information */
+export interface Implementation {
+  name: string;
+  version: string;
+}
+
+/** Client capabilities */
+export interface ClientCapabilities {
+  // Client can handle these features
+  readonly experimental?: Record<string, unknown>;
+  readonly roots?: { listChanged?: boolean };
+  readonly sampling?: Record<string, unknown>;
+}
+
+/** Server capabilities */
+export interface ServerCapabilities {
+  // Server provides these features
+  readonly experimental?: Record<string, unknown>;
+  readonly logging?: Record<string, unknown>;
+  readonly prompts?: { listChanged?: boolean };
+  readonly resources?: { subscribe?: boolean; listChanged?: boolean };
+  readonly tools?: { listChanged?: boolean };
+}
+
+// ============================================================================
+// MCP Tool Definitions
+// ============================================================================
+
+/** Tool definition for tool/list */
+export interface Tool {
+  name: string;
+  description: string;
+  inputSchema: ToolInputSchema;
+}
+
+/** Tool input schema (JSON Schema) */
+export interface ToolInputSchema {
+  type: 'object';
+  properties?: Record<string, unknown>;
+  required?: string[];
+  additionalProperties?: boolean;
+}
+
+/** Tool call request */
+export interface ToolCallRequest {
+  name: string;
+  arguments?: Record<string, unknown>;
+}
+
+/** Tool call result */
+export interface ToolCallResult {
+  content: ToolContent[];
+  isError?: boolean;
+}
+
+/** Tool content types */
+export type ToolContent = TextContent | ImageContent;
+
+/** Text content */
+export interface TextContent {
+  type: 'text';
+  text: string;
+}
+
+/** Image content */
+export interface ImageContent {
+  type: 'image';
+  data: string; // base64 encoded
+  mimeType: string;
+}
+
+// ============================================================================
+// MCP Tool List
+// ============================================================================
+
+/** All available tool names */
+export const TOOL_NAMES = ['memory_load', 'memory_update'] as const;
+
+/** Tool name type */
+export type ToolName = (typeof TOOL_NAMES)[number];
+
+/** Tool definitions for MCP server */
+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.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Optional memory id for direct fetch' },
+        sessionId: {
+          type: 'string',
+          description: 'Optional session UUID to load current CLI/task context',
+        },
+        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: {
+          type: 'string',
+          enum: ['stm', 'all'],
+          description: 'stm for short-term context window; all for broader retrieval',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    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.',
+    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' },
+        entryType: {
+          type: 'string',
+          enum: ['decision', 'preference', 'knowledge', 'todo', 'state_change'],
+        },
+        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,
+    },
+  },
+] as const;
+
+// ============================================================================
+// MCP Methods
+// ============================================================================
+
+/** All MCP method names */
+export const MCP_METHODS = {
+  // Lifecycle
+  INITIALIZE: 'initialize',
+  INITIALIZED: 'notifications/initialized',
+  SHUTDOWN: 'shutdown',
+  EXIT: 'exit',
+
+  // Tools
+  TOOLS_LIST: 'tools/list',
+  TOOLS_CALL: 'tools/call',
+
+  // Logging
+  LOGGING_MESSAGE: 'notifications/message',
+
+  // Progress
+  PROGRESS: 'notifications/progress',
+} as const;
+
+// ============================================================================
+// Error Codes (Standard MCP + Custom)
+// ============================================================================
+
+/** Standard JSON-RPC error codes */
+export const JSONRPC_ERROR_CODES = {
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+} as const;
+
+/** MemHub custom error codes */
+export const MEMHUB_ERROR_CODES = {
+  NOT_FOUND: -32001,
+  STORAGE_ERROR: -32002,
+  VALIDATION_ERROR: -32003,
+  DUPLICATE_ERROR: -32004,
+} as const;
+
+/** Combined error codes */
+export const ERROR_CODES = {
+  ...JSONRPC_ERROR_CODES,
+  ...MEMHUB_ERROR_CODES,
+} as const;
+
+// ============================================================================
+// Utility Types
+// ============================================================================
+
+/** Helper type to extract result type from a tool name */
+export type ToolResult<T extends ToolName> = T extends 'memory_load'
+  ? { items: Memory[]; total: number }
+  : T extends 'memory_update'
+    ? {
+        id: string;
+        sessionId: string;
+        filePath: string;
+        created: boolean;
+        updated: boolean;
+        memory: Memory;
+      }
+    : never;
+
+/** Helper type to extract input type from a tool name */
+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';
+        title?: string;
+        content: string;
+        tags?: string[];
+        category?: string;
+        importance?: number;
+      }
+    : never;

package/src/contracts/schemas.ts

@@ -0,0 +1,311 @@
+/**
+ * Zod schemas for runtime validation
+ * All schemas correspond to types defined in types.ts
+ */
+
+import { z } from 'zod';
+
+// ============================================================================
+// Primitive Schemas
+// ============================================================================
+
+/** UUID v4 validation schema */
+export const UUIDSchema = z.string().uuid().brand<'UUID'>();
+
+/** ISO 8601 timestamp validation */
+export const ISO8601TimestampSchema = z.string().datetime().brand<'ISO8601'>();
+
+/** Slug validation (URL-friendly string) */
+export const SlugSchema = z
+  .string()
+  .min(1)
+  .max(100)
+  .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, 'Must be a valid URL slug');
+
+/** Tag name validation */
+export const TagSchema = z
+  .string()
+  .min(1)
+  .max(50)
+  .regex(/^[a-z0-9-]+$/, 'Tags can only contain lowercase letters, numbers, and hyphens');
+
+/** Category name validation */
+export const CategorySchema = z
+  .string()
+  .min(1)
+  .max(50)
+  .regex(/^[a-z0-9-]+$/, 'Category can only contain lowercase letters, numbers, and hyphens');
+
+/** Importance level validation (1-5) */
+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',
+]);
+
+// ============================================================================
+// Memory Schemas
+// ============================================================================
+
+/** Memory front matter schema (YAML portion) */
+export const MemoryFrontMatterSchema = z.object({
+  id: UUIDSchema,
+  created_at: ISO8601TimestampSchema,
+  updated_at: ISO8601TimestampSchema,
+  session_id: UUIDSchema.optional(),
+  entry_type: MemoryEntryTypeSchema.optional(),
+  tags: z.array(TagSchema).default([]),
+  category: CategorySchema.default('general'),
+  importance: ImportanceSchema.default(3),
+});
+
+/** Complete memory schema */
+export const MemorySchema = z.object({
+  id: UUIDSchema,
+  createdAt: ISO8601TimestampSchema,
+  updatedAt: ISO8601TimestampSchema,
+  sessionId: UUIDSchema.optional(),
+  entryType: MemoryEntryTypeSchema.optional(),
+  tags: z.array(z.string()).readonly(),
+  category: CategorySchema,
+  importance: ImportanceSchema,
+  title: z.string().min(1).max(200),
+  content: z.string().max(100000),
+});
+
+/** Memory file schema */
+export const MemoryFileSchema = z.object({
+  path: z.string().min(1),
+  filename: z.string().min(1),
+  content: z.string(),
+  modifiedAt: ISO8601TimestampSchema,
+});
+
+// ============================================================================
+// Result Schemas
+// ============================================================================
+
+/** Search result schema */
+export const SearchResultSchema = z.object({
+  memory: MemorySchema,
+  score: z.number().min(0).max(1),
+  matches: z.array(z.string()),
+});
+
+/** List result schema */
+export const ListResultSchema = z.object({
+  memories: z.array(MemorySchema),
+  total: z.number().int().nonnegative(),
+  hasMore: z.boolean(),
+});
+
+/** Create result schema */
+export const CreateResultSchema = z.object({
+  id: UUIDSchema,
+  filePath: z.string().min(1),
+  memory: MemorySchema,
+});
+
+/** Update result schema */
+export const UpdateResultSchema = z.object({
+  memory: MemorySchema,
+});
+
+/** Delete result schema */
+export const DeleteResultSchema = z.object({
+  success: z.boolean(),
+  filePath: z.string().min(1),
+});
+
+// ============================================================================
+// Filter and Query Schemas
+// ============================================================================
+
+/** Sort field enum */
+export const SortFieldSchema = z.enum(['createdAt', 'updatedAt', 'title', 'importance']);
+
+/** Sort order enum */
+export const SortOrderSchema = z.enum(['asc', 'desc']);
+
+/** Memory filter schema */
+export const MemoryFilterSchema = z.object({
+  category: CategorySchema.optional(),
+  tags: z.array(TagSchema).optional(),
+  fromDate: ISO8601TimestampSchema.optional(),
+  toDate: ISO8601TimestampSchema.optional(),
+});
+
+/** Pagination options schema */
+export const PaginationOptionsSchema = z.object({
+  limit: z.number().int().min(1).max(100).default(20),
+  offset: z.number().int().min(0).default(0),
+});
+
+/** Sort options schema */
+export const SortOptionsSchema = z.object({
+  sortBy: SortFieldSchema.default('createdAt'),
+  sortOrder: SortOrderSchema.default('desc'),
+});
+
+// ============================================================================
+// MCP Tool Input Schemas
+// ============================================================================
+
+/** Create memory input schema */
+export const CreateMemoryInputSchema = z.object({
+  title: z.string().min(1).max(200),
+  content: z.string().max(100000),
+  tags: z.array(TagSchema).default([]),
+  category: CategorySchema.default('general'),
+  importance: ImportanceSchema.default(3),
+});
+
+/** Read memory input schema */
+export const ReadMemoryInputSchema = z.object({
+  id: UUIDSchema,
+});
+
+/** Update memory input schema */
+export const UpdateMemoryInputSchema = z.object({
+  id: UUIDSchema,
+  title: z.string().min(1).max(200).optional(),
+  content: z.string().max(100000).optional(),
+  tags: z.array(TagSchema).optional(),
+  category: CategorySchema.optional(),
+  importance: ImportanceSchema.optional(),
+});
+
+/** Delete memory input schema */
+export const DeleteMemoryInputSchema = z.object({
+  id: UUIDSchema,
+});
+
+/** List memory input schema */
+export const ListMemoryInputSchema = z.object({
+  category: CategorySchema.optional(),
+  tags: z.array(TagSchema).optional(),
+  fromDate: ISO8601TimestampSchema.optional(),
+  toDate: ISO8601TimestampSchema.optional(),
+  limit: z.number().int().min(1).max(100).optional(),
+  offset: z.number().int().min(0).optional(),
+  sortBy: SortFieldSchema.optional(),
+  sortOrder: SortOrderSchema.optional(),
+});
+
+/** Search memory input schema */
+export const SearchMemoryInputSchema = z.object({
+  query: z.string().min(1).max(1000),
+  limit: z.number().int().min(1).max(100).optional(),
+  category: CategorySchema.optional(),
+  tags: z.array(TagSchema).optional(),
+});
+
+/** 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 */
+export const MemoryUpdateInputV2Schema = z.object({
+  id: UUIDSchema.optional(),
+  sessionId: UUIDSchema.optional(),
+  mode: z.enum(['append', 'upsert']).default('append'),
+  entryType: MemoryEntryTypeSchema.optional(),
+  title: z.string().min(1).max(200).optional(),
+  content: z.string().min(1).max(100000),
+  tags: z.array(TagSchema).optional(),
+  category: CategorySchema.optional(),
+  importance: ImportanceSchema.optional(),
+});
+
+// ============================================================================
+// MCP Tool Output Schemas
+// ============================================================================
+
+/** Create memory output schema */
+export const CreateMemoryOutputSchema = CreateResultSchema;
+
+/** Read memory output schema */
+export const ReadMemoryOutputSchema = z.object({
+  memory: MemorySchema,
+});
+
+/** Update memory output schema */
+export const UpdateMemoryOutputSchema = UpdateResultSchema;
+
+export const MemoryLoadOutputSchema = z.object({
+  items: z.array(MemorySchema),
+  total: z.number().int().nonnegative(),
+});
+
+export const MemoryUpdateOutputSchema = z.object({
+  id: UUIDSchema,
+  sessionId: UUIDSchema,
+  filePath: z.string().min(1),
+  created: z.boolean(),
+  updated: z.boolean(),
+  memory: MemorySchema,
+});
+
+/** Delete memory output schema */
+export const DeleteMemoryOutputSchema = DeleteResultSchema;
+
+/** List memory output schema */
+export const ListMemoryOutputSchema = ListResultSchema;
+
+/** Search memory output schema */
+export const SearchMemoryOutputSchema = z.object({
+  results: z.array(SearchResultSchema),
+  total: z.number().int().nonnegative(),
+});
+
+/** Get categories output schema */
+export const GetCategoriesOutputSchema = z.object({
+  categories: z.array(CategorySchema),
+});
+
+/** Get tags output schema */
+export const GetTagsOutputSchema = z.object({
+  tags: z.array(TagSchema),
+});
+
+// ============================================================================
+// Configuration Schemas
+// ============================================================================
+
+/** Configuration schema */
+export const ConfigSchema = z.object({
+  storagePath: z.string().min(1),
+  logLevel: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+});
+
+// ============================================================================
+// Type Extraction from Schemas
+// ============================================================================
+
+/** Inferred Memory type from schema */
+export type MemoryFromSchema = z.infer<typeof MemorySchema>;
+
+/** Inferred CreateInput type from schema */
+export type CreateMemoryInputFromSchema = z.infer<typeof CreateMemoryInputSchema>;
+
+/** Inferred UpdateInput type from schema */
+export type UpdateMemoryInputFromSchema = z.infer<typeof UpdateMemoryInputSchema>;
+
+/** Inferred ListInput type from schema */
+export type ListMemoryInputFromSchema = z.infer<typeof ListMemoryInputSchema>;
+
+/** Inferred SearchInput type from schema */
+export type SearchMemoryInputFromSchema = z.infer<typeof SearchMemoryInputSchema>;