@synth-coder/memhub 0.2.3 → 0.2.4

package/docs/mcp-tools.md

@@ -0,0 +1,136 @@
+# MCP Tools Reference
+
+MemHub exposes two MCP tools for AI agents to manage persistent memory.
+
+---
+
+## memory_load
+
+Load relevant memories to get context for the current task.
+
+### Parameters
+
+| Parameter   | Type     | Required | Description                                                 |
+| ----------- | -------- | -------- | ----------------------------------------------------------- |
+| `query`     | string   | No       | Search query to filter memories                             |
+| `tags`      | string[] | No       | Filter by tags                                              |
+| `limit`     | number   | No       | Max memories to return (default: 10)                        |
+| `entryType` | string   | No       | Filter by type: `preference`, `decision`, `context`, `fact` |
+
+### Returns
+
+```json
+{
+  "memories": [
+    {
+      "id": "uuid",
+      "title": "Memory title",
+      "content": "Memory content...",
+      "tags": ["tag1", "tag2"],
+      "category": "engineering",
+      "importance": 4,
+      "createdAt": "2026-03-04T10:00:00.000Z",
+      "updatedAt": "2026-03-04T10:00:00.000Z"
+    }
+  ],
+  "count": 1
+}
+```
+
+### When to Call
+
+- Starting a new conversation or task
+- User mentions "before", "remember", "last time"
+- Uncertain about user preferences or constraints
+- Need project context (tech stack, conventions)
+
+### Example
+
+```json
+{
+  "query": "testing framework",
+  "tags": ["preference"],
+  "limit": 5
+}
+```
+
+---
+
+## memory_update
+
+Store new memories or update existing ones.
+
+### Parameters
+
+| Parameter    | Type     | Required | Description                                |
+| ------------ | -------- | -------- | ------------------------------------------ |
+| `title`      | string   | Yes      | Short, descriptive title                   |
+| `content`    | string   | Yes      | Detailed memory content                    |
+| `tags`       | string[] | No       | Tags for categorization                    |
+| `entryType`  | string   | No       | Memory type (default: `fact`)              |
+| `category`   | string   | No       | Category (e.g., `engineering`, `business`) |
+| `importance` | number   | No       | Importance 1-5 (default: 3)                |
+| `id`         | string   | No       | Existing memory ID to update               |
+
+### Entry Types
+
+| Type         | Purpose                                            |
+| ------------ | -------------------------------------------------- |
+| `preference` | User preferences (coding style, framework choices) |
+| `decision`   | Architecture decisions, technology choices         |
+| `context`    | Project context (team, processes, constraints)     |
+| `fact`       | Learned facts, important notes                     |
+
+### Returns
+
+```json
+{
+  "id": "uuid",
+  "title": "Memory title",
+  "createdAt": "2026-03-04T10:00:00.000Z"
+}
+```
+
+### When to Call
+
+- User explicitly expresses a preference
+- Made a significant decision with reasoning
+- Discovered important project context
+- User corrected an assumption
+
+### Example
+
+```json
+{
+  "title": "Use Vitest for Testing",
+  "content": "User prefers Vitest over Jest for all new projects. Reason: faster test execution and better ESM support.",
+  "tags": ["testing", "preference"],
+  "entryType": "preference",
+  "importance": 4
+}
+```
+
+---
+
+## Best Practices
+
+### What to Store
+
+**Good candidates:**
+
+- User preferences (coding style, frameworks)
+- Technical decisions and their reasoning
+- Project constraints and conventions
+- Lessons learned from mistakes
+
+**Avoid storing:**
+
+- Temporary information
+- One-time tasks
+- Sensitive data (API keys, passwords)
+
+### Memory Principles
+
+1. **Natural trigger** - Memory calls should be context-driven
+2. **Value first** - Only store what future conversations benefit from
+3. **Preferences matter** - User preferences are the most valuable memories

package/docs/user-guide.md

@@ -0,0 +1,182 @@
+# MemHub User Guide
+
+MemHub is a Git-friendly memory system for AI coding agents. It helps your AI remember preferences, decisions, and project context across conversations.
+
+## Installation
+
+### Quick Setup (Recommended)
+
+Configure MemHub for your AI agent with one command:
+
+```bash
+npx -y @synth-coder/memhub init
+```
+
+This will:
+
+1. Add MCP server config to your agent's configuration file
+2. Add MemHub usage instructions to your agent's rules file
+
+### Supported Agents
+
+| Agent         | Global Config                         | Local Config                        |
+| ------------- | ------------------------------------- | ----------------------------------- |
+| Claude Code   | `~/.claude/settings.json`             | `.mcp.json`                         |
+| Cursor        | `~/.cursor/mcp.json`                  | `.cursor/mcp.json`                  |
+| Cline         | `~/.cline/mcp.json`                   | `.cline/mcp.json`                   |
+| Windsurf      | `~/.codeium/windsurf/mcp_config.json` | `.codeium/windsurf/mcp_config.json` |
+| Factory Droid | `~/.factory/mcp.json`                 | `.factory/mcp.json`                 |
+| Gemini CLI    | `~/.gemini/settings.json`             | `.gemini/settings.json`             |
+| Codex         | `~/.codex/config.toml`                | `.codex/config.toml`                |
+
+### CLI Options
+
+```bash
+# Interactive selection (global - default)
+npx -y @synth-coder/memhub init
+
+# Specify agent
+npx -y @synth-coder/memhub init -a claude-code
+
+# Configure for current project only (local)
+npx -y @synth-coder/memhub init -a cursor -l
+
+# Update existing configuration
+npx -y @synth-coder/memhub init -a claude-code --force
+```
+
+| Option               | Description                                     |
+| -------------------- | ----------------------------------------------- |
+| `-a, --agent <name>` | Agent type (skip interactive)                   |
+| `-l, --local`        | Configure for current project (default: global) |
+| `-f, --force`        | Update existing configuration                   |
+
+---
+
+## How It Works
+
+### Memory Tools
+
+MemHub provides two MCP tools for your AI agent:
+
+#### `memory_load` - Recall Context
+
+Your AI calls this when it needs to remember something:
+
+- User mentions "before", "remember", "last time"
+- Uncertain about user preferences
+- Need historical context for a decision
+
+#### `memory_update` - Store Knowledge
+
+Your AI calls this when it learns something worth remembering:
+
+- User expresses a preference ("I prefer functional components")
+- Made a significant decision with reasoning
+- Discovered important project context
+- User corrected an assumption
+
+### Memory Types
+
+| Type         | Purpose             | Example                              |
+| ------------ | ------------------- | ------------------------------------ |
+| `preference` | User preferences    | "Prefers TypeScript over JavaScript" |
+| `decision`   | Technical decisions | "Using PostgreSQL for scalability"   |
+| `context`    | Project context     | "Team uses conventional commits"     |
+| `fact`       | Learned facts       | "API rate limit is 1000 req/min"     |
+
+---
+
+## Storage
+
+### Where Memories Are Stored
+
+By default, memories are stored in `~/.memhub/` (global) or `./memories/` (local).
+
+```bash
+# Custom storage location
+MEMHUB_STORAGE_PATH=/path/to/memories npx -y @synth-coder/memhub
+```
+
+### File Format
+
+Memories are plain Markdown files with YAML front matter:
+
+```markdown
+---
+id: '550e8400-e29b-41d4-a716-446655440000'
+created_at: '2026-03-04T10:00:00.000Z'
+tags:
+  - architecture
+  - tdd
+category: 'engineering'
+importance: 4
+---
+
+# Use Contract-First Design
+
+Define tool contracts and schemas before implementation.
+```
+
+### Git Integration
+
+Since memories are plain text files, you can:
+
+- Commit them to your repository
+- Review changes in pull requests
+- Revert if needed
+- Share with your team
+
+---
+
+## Environment Variables
+
+| Variable              | Default     | Description                                 |
+| --------------------- | ----------- | ------------------------------------------- |
+| `MEMHUB_STORAGE_PATH` | `~/.memhub` | Memory storage directory                    |
+| `MEMHUB_LOG_LEVEL`    | `info`      | Log level: `debug`, `info`, `warn`, `error` |
+
+---
+
+## Tips
+
+### What to Remember
+
+**Good candidates:**
+
+- User preferences (coding style, frameworks)
+- Technical decisions and their reasoning
+- Project constraints and conventions
+- Lessons learned from mistakes
+
+**Avoid storing:**
+
+- Temporary information
+- One-time tasks
+- Sensitive data (API keys, passwords)
+
+### Memory Principles
+
+1. **Natural trigger** - Memory calls should be context-driven, not scheduled
+2. **Value first** - Only store what future conversations will benefit from
+3. **Preferences matter** - User preferences are the most valuable memories
+
+---
+
+## Troubleshooting
+
+### Configuration not working?
+
+1. Restart your AI agent after running `init`
+2. Check the config file exists and contains `memhub` server
+3. Try with `--force` to update existing configuration
+
+### Memories not loading?
+
+1. Check `MEMHUB_STORAGE_PATH` is correct
+2. Verify the directory contains `.md` files
+3. Check file permissions
+
+### Need help?
+
+- GitHub Issues: https://github.com/synth-coder/memhub/issues

package/package.json

@@ -1,59 +1,61 @@
-{
-  "name": "@synth-coder/memhub",
-  "version": "0.2.3",
-  "description": "A Git-friendly memory hub using Markdown-based storage with YAML Front Matter",
-  "type": "module",
-  "main": "dist/src/index.js",
-  "types": "dist/src/index.d.ts",
-  "bin": {
-    "memhub": "dist/src/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": {
-    "@lancedb/lancedb": "^0.26.2",
-    "@modelcontextprotocol/sdk": "^1.27.1",
-    "@xenova/transformers": "^2.17.2",
-    "proper-lockfile": "^4.1.2",
-    "sharp": "^0.34.5",
-    "yaml": "^2.8.2",
-    "zod": "^3.25.76"
-  },
-  "devDependencies": {
-    "@types/node": "^20.19.35",
-    "@types/proper-lockfile": "^4.1.4",
-    "@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"
-  }
-}
+{
+  "name": "@synth-coder/memhub",
+  "version": "0.2.4",
+  "description": "A Git-friendly memory hub using Markdown-based storage with YAML Front Matter",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "bin": {
+    "memhub": "dist/src/cli/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "memory",
+    "markdown",
+    "yaml",
+    "git-friendly"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^1.1.0",
+    "@lancedb/lancedb": "^0.26.2",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@xenova/transformers": "^2.17.2",
+    "proper-lockfile": "^4.1.2",
+    "sharp": "^0.34.5",
+    "smol-toml": "^1.6.0",
+    "yaml": "^2.8.2",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.35",
+    "@types/proper-lockfile": "^4.1.4",
+    "@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": ">=20.0.0"
+  },
+  "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"
+  }
+}

package/src/cli/agents/claude-code.ts

@@ -0,0 +1,14 @@
+/**
+ * Claude Code MCP configuration generator
+ */
+
+export function generateClaudeCodeConfig(_memhubPath: string): Record<string, unknown> {
+  return {
+    mcpServers: {
+      memhub: {
+        command: 'npx',
+        args: ['-y', '@synth-coder/memhub'],
+      },
+    },
+  };
+}

package/src/cli/agents/cline.ts

@@ -0,0 +1,14 @@
+/**
+ * Cline MCP configuration generator
+ */
+
+export function generateClineConfig(_memhubPath: string): Record<string, unknown> {
+  return {
+    mcpServers: {
+      memhub: {
+        command: 'npx',
+        args: ['-y', '@synth-coder/memhub'],
+      },
+    },
+  };
+}

package/src/cli/agents/codex.ts

@@ -0,0 +1,14 @@
+/**
+ * Codex MCP configuration generator
+ */
+
+export function generateCodexConfig(_memhubPath: string): Record<string, unknown> {
+  return {
+    mcpServers: {
+      memhub: {
+        command: 'npx',
+        args: ['-y', '@synth-coder/memhub'],
+      },
+    },
+  };
+}

package/src/cli/agents/cursor.ts

@@ -0,0 +1,14 @@
+/**
+ * Cursor MCP configuration generator
+ */
+
+export function generateCursorConfig(_memhubPath: string): Record<string, unknown> {
+  return {
+    mcpServers: {
+      memhub: {
+        command: 'npx',
+        args: ['-y', '@synth-coder/memhub'],
+      },
+    },
+  };
+}

package/src/cli/agents/factory-droid.ts

@@ -0,0 +1,14 @@
+/**
+ * Factory Droid MCP configuration generator
+ */
+
+export function generateFactoryDroidConfig(_memhubPath: string): Record<string, unknown> {
+  return {
+    mcpServers: {
+      memhub: {
+        command: 'npx',
+        args: ['-y', '@synth-coder/memhub'],
+      },
+    },
+  };
+}

package/src/cli/agents/gemini-cli.ts

@@ -0,0 +1,14 @@
+/**
+ * Gemini CLI MCP configuration generator
+ */
+
+export function generateGeminiCliConfig(_memhubPath: string): Record<string, unknown> {
+  return {
+    mcpServers: {
+      memhub: {
+        command: 'npx',
+        args: ['-y', '@synth-coder/memhub'],
+      },
+    },
+  };
+}

package/src/cli/agents/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Agent configuration generators index
+ */
+
+export { generateCursorConfig } from './cursor.js';
+export { generateClaudeCodeConfig } from './claude-code.js';
+export { generateClineConfig } from './cline.js';
+export { generateWindsurfConfig } from './windsurf.js';
+export { generateFactoryDroidConfig } from './factory-droid.js';
+export { generateGeminiCliConfig } from './gemini-cli.js';
+export { generateCodexConfig } from './codex.js';
+
+import type { AgentType } from '../types.js';
+import { generateCursorConfig } from './cursor.js';
+import { generateClaudeCodeConfig } from './claude-code.js';
+import { generateClineConfig } from './cline.js';
+import { generateWindsurfConfig } from './windsurf.js';
+import { generateFactoryDroidConfig } from './factory-droid.js';
+import { generateGeminiCliConfig } from './gemini-cli.js';
+import { generateCodexConfig } from './codex.js';
+
+export type ConfigGenerator = (memhubPath: string) => Record<string, unknown>;
+
+const generators: Record<AgentType, ConfigGenerator> = {
+  cursor: generateCursorConfig,
+  'claude-code': generateClaudeCodeConfig,
+  cline: generateClineConfig,
+  windsurf: generateWindsurfConfig,
+  'factory-droid': generateFactoryDroidConfig,
+  'gemini-cli': generateGeminiCliConfig,
+  codex: generateCodexConfig,
+};
+
+export function getConfigGenerator(agentId: AgentType): ConfigGenerator {
+  return generators[agentId];
+}

package/src/cli/agents/windsurf.ts

@@ -0,0 +1,14 @@
+/**
+ * Windsurf MCP configuration generator
+ */
+
+export function generateWindsurfConfig(_memhubPath: string): Record<string, unknown> {
+  return {
+    mcpServers: {
+      memhub: {
+        command: 'npx',
+        args: ['-y', '@synth-coder/memhub'],
+      },
+    },
+  };
+}