@synth-coder/memhub 0.2.2 → 0.2.4

package/.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [18.x, 20.x]
+        node-version: [20.x, 22.x]
 
     steps:
       - name: Checkout repository
@@ -23,22 +23,40 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-          cache: 'npm'
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Get pnpm store directory
+        shell: bash
+        run: |
+          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_OUTPUT
+        id: pnpm-cache
+
+      - name: Setup pnpm cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
 
       - name: Install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
 
       - name: Run linter
-        run: npm run lint
+        run: pnpm run lint
 
       - name: Check formatting
-        run: npm run format:check
+        run: pnpm run format:check
 
       - name: Run type check
-        run: npm run typecheck
+        run: pnpm run typecheck
 
       - name: Run tests with coverage
-        run: npm run test:coverage
+        run: pnpm run test:coverage
 
       - name: Upload coverage reports
         uses: codecov/codecov-action@v3
@@ -60,15 +78,33 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: 20.x
-          cache: 'npm'
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Get pnpm store directory
+        shell: bash
+        run: |
+          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_OUTPUT
+        id: pnpm-cache
+
+      - name: Setup pnpm cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
 
       - name: Install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
 
       - name: Build project
-        run: npm run build
+        run: pnpm run build
 
       - name: Check build output
         run: |
-          test -f dist/index.js
-          test -f dist/server/mcp-server.js
+          test -f dist/src/index.js
+          test -f dist/src/server/mcp-server.js

package/.github/workflows/release.yml

@@ -0,0 +1,67 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  quality:
+    name: Quality Gate
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run quality gate
+        run: pnpm run quality
+
+  publish:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+    needs: quality
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm run build
+
+      - name: Publish to npm
+        run: pnpm publish --no-git-checks
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          generate_release_notes: true

package/AGENTS.md

@@ -1,26 +1,167 @@
-你是Alex。
+# AGENTS.md - MemHub Project Guide
 
-## 我是谁
+## Project Overview
 
-一个用能力说话的人。不装权威，不讨好谁，只做一件事：**解决你的问题**。
+MemHub is a Git-friendly memory MCP server for coding agents. It stores decisions, preferences, and reusable knowledge as plain Markdown files with YAML front matter.
 
-## 我相信什么
+**Tech Stack**: TypeScript (ES2022), Node.js 18+, MCP SDK, Zod, LanceDB, Transformers.js
 
-**能力 → 价值 → 尊重**
+---
 
-- 能力是能解决多少真实问题，不是知道多少概念
-- 价值是我能帮你省多少时间，不是我说了多少话
-- 尊重是你觉得我值不值得信任，不是我有多客气
+## Dev Environment
 
-## 我怎么做事
+```bash
+npx pnpm install        # Install dependencies
+npx pnpm run build      # Compile TypeScript
+npx pnpm run quality    # Quality gate (lint + typecheck + test + coverage)
+```
 
-| 原则 | 含义 |
-|------|------|
-| 说不该说的话 | 不废话，不解释显然的东西，不低估你的智商 |
-| 承认不懂的事 | 不装懂，但给出找答案的路径 |
-| 交付可用的东西 | 答案可执行，方案可落地，风险有预警 |
-| 记住你的偏好 | 一次比一次更懂你，越用越顺手 |
+| Command | Description |
+|---------|-------------|
+| `npx pnpm run build` | Compile TypeScript |
+| `npx pnpm run lint` | ESLint check |
+| `npx pnpm run lint:fix` | Auto-fix lint issues |
+| `npx pnpm run format` | Format code with Prettier |
+| `npx pnpm run typecheck` | TypeScript type check |
+| `npx pnpm run test` | Run Vitest tests |
+| `npx pnpm run test:coverage` | Tests with coverage |
+| `npx pnpm run quality` | Full quality gate |
+| `npx pnpm vitest run -t "test name"` | Run specific test |
 
-## 一句话
+---
 
-**你的时间宝贵，我的价值在于帮你解决问题，而不是陪你聊天。**
+## Project Structure
+
+```
+src/
+  contracts/    # Type definitions, Zod schemas, MCP contracts
+  cli/          # CLI commands (init, etc.)
+  server/       # MCP stdio server entry point
+  services/     # Business logic (MemoryService, EmbeddingService)
+  storage/      # Storage layer (Markdown, VectorIndex)
+  utils/        # Shared utilities (slugify, etc.)
+test/           # Vitest unit tests mirroring src/ structure
+docs/           # Documentation
+```
+
+---
+
+## Coding Style
+
+### TypeScript Conventions
+- Use `readonly` for immutable fields in interfaces
+- Use `type` for aliases, `interface` for object shapes
+- Prefer `import type` for type-only imports
+- Use ESM: `.js` extension in imports, `verbatimModuleSyntax`
+- Explicit return types on exported functions
+- Use Zod for runtime validation
+
+### File Naming
+- `kebab-case.ts` for all files
+- Test files: `<module>.test.ts` or `<module>-edge.test.ts`
+
+### Example Code Style
+
+```typescript
+// Types with readonly fields
+export interface Memory {
+  readonly id: UUID;
+  readonly tags: readonly string[];
+}
+
+// Service with explicit types
+export class MemoryService {
+  constructor(private readonly config: MemoryServiceConfig) {}
+
+  async create(input: CreateMemoryInput): Promise<CreateResult> {
+    // implementation
+  }
+}
+
+// Zod schema for validation
+export const MemorySchema = z.object({
+  id: z.string().uuid(),
+  tags: z.array(z.string()),
+});
+```
+
+---
+
+## Workflows
+
+### Add New MCP Tool
+
+1. **Define types** → `src/contracts/types.ts`
+2. **Define schema** → `src/contracts/schemas.ts`
+3. **Register tool** → `src/contracts/mcp.ts`
+4. **Implement logic** → `src/services/memory-service.ts`
+5. **Add tests** → `test/services/memory-service.test.ts`
+6. **Update docs** → `docs/mcp-tools.md`
+7. **Run quality gate** → `npx pnpm run quality`
+
+### Support New Agent
+
+1. **Add agent type** → `src/cli/types.ts` (AgentType union)
+2. **Create agent config** → `src/cli/agents/<agent-name>.ts`
+3. **Register in init** → `src/cli/init.ts` (AGENT_CONFIGS map)
+4. **Add tests** → `test/cli/init.test.ts`
+5. **Update docs** → `docs/user-guide.md` (supported agents table)
+6. **Update README** → `README.md` and `README.zh-CN.md`
+7. **Run quality gate** → `npx pnpm run quality`
+
+### Release New Version
+
+1. **Update version** → `package.json`
+2. **Update Roadmap** → `README.md` (mark released items)
+3. **Run quality gate** → `npx pnpm run quality`
+4. **Commit & tag** → `git commit && git tag v<x.y.z>`
+5. **Publish** → `npm publish`
+
+---
+
+## Documentation Sync
+
+Documentation must stay in sync with code. **Update docs when changing:**
+
+| Code Change | Update Doc |
+|-------------|------------|
+| MCP tool parameters/returns | `docs/mcp-tools.md` |
+| CLI options/behavior | `docs/user-guide.md` |
+| New agent support | `docs/user-guide.md`, `README.md` |
+| Version number | `README.md` Roadmap |
+
+---
+
+## Testing Guidelines
+
+- **Coverage threshold**: >= 80%
+- Tests mirror `src/` structure in `test/` directory
+- Use Vitest: `describe`, `it`, `expect` pattern
+- Edge cases go in `*-edge.test.ts` files
+- Run `npx pnpm run quality` before committing
+
+---
+
+## Git Workflow
+
+- Commit message: `type: description` (feat/fix/docs/chore/refactor/test)
+- Always run quality gate before committing
+- PR title: `[scope] Description`
+
+---
+
+## Dos and Don'ts
+
+### Do
+- Run `npx pnpm run quality` before committing
+- Add tests for new code
+- Use `import type` for type-only imports
+- Keep functions small and focused
+- Update types, schemas, and docs together
+
+### Don't
+- Skip the quality gate
+- Use `any` without justification
+- Mutate function parameters
+- Add code without corresponding tests
+- Commit directly to main (use branches for features)

package/README.md

@@ -2,68 +2,67 @@
 
 Git-friendly memory MCP server for coding agents.
 
-MemHub stores decisions, preferences, and reusable knowledge as plain Markdown files with YAML front matter, so everything is easy to review, diff, and version with Git.
-
 ---
 
-## Why MemHub
+## Quick Start
 
-- **Git-native**: all memory is plain text files
-- **Agent-friendly**: exposed as MCP tools over stdio
-- **Human-readable**: YAML metadata + Markdown body
-- **Quality-gated**: lint + typecheck + tests + coverage gate
+### One-Line Setup
 
----
+Configure MemHub for your AI agent with a single command:
 
-## Features
+```bash
+npx -y @synth-coder/memhub init
+```
 
-- Markdown-based memory storage (`.md`)
-- YAML Front Matter metadata (`id`, `session_id`, `entry_type`, `tags`, `category`, `importance`, timestamps)
-- STM-first 2-tool interface: `memory_load` + `memory_update`
-- Concurrent CLI-safe storage layout: `YYYY-MM-DD/session_uuid/...`
-- MCP stdio server compatible with MCP clients
+This launches an interactive prompt to select your agent. MemHub 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:**
 
-## Quick Start
+| Agent | Config File | Instructions File |
+|-------|-------------|-------------------|
+| Claude Code | `~/.claude/settings.json` | `~/.claude/CLAUDE.md` |
+| Cursor | `~/.cursor/mcp.json` | `~/.cursorrules` |
+| Cline | `~/.cline/mcp.json` | `~/.clinerules` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | `~/.windsurfrules` |
+| Factory Droid | `~/.factory/mcp.json` | `~/.factory/AGENTS.md` |
+| Gemini CLI | `~/.gemini/settings.json` | `~/.gemini/GEMINI.md` |
+| Codex | `~/.codex/config.toml` | `~/.codex/AGENTS.md` |
 
-### 1) Install from npm
+### CLI Options
 
 ```bash
-npm i @synth-coder/memhub
-```
+# Interactive selection (global - default)
+npx -y @synth-coder/memhub init
 
-### 2) Or install dependencies for local development
+# Skip interactive prompt
+npx -y @synth-coder/memhub init -a claude-code
 
-```bash
-npm install
-```
-
-### 3) Build
-
-```bash
-npm run build
-```
+# Configure for current project only (local)
+npx -y @synth-coder/memhub init -a cursor -l
 
-### 4) Run quality gate
-```bash
-npm run quality
+# Update existing configuration
+npx -y @synth-coder/memhub init -a claude-code --force
 ```
 
----
-
-## Use as MCP Server (stdio)
+| Option | Description |
+|--------|-------------|
+| `-a, --agent <name>` | Agent type (skip interactive) |
+| `-l, --local` | Configure for current project (default: global) |
+| `-f, --force` | Update existing configuration |
 
-### Option A: run directly via npx (recommended)
+### Run as MCP Server
 
 ```bash
 npx -y @synth-coder/memhub
 ```
 
 > On Windows, do **not** append `memhub` after the package name.
-> If a source `.js` file opens in editor, upgrade to latest package version (`0.1.2+`) and retry.
 
-Example MCP client config:
+### Manual Configuration
+
+If you prefer manual setup, add this to your MCP client config:
 
 ```json
 {
@@ -80,24 +79,109 @@ Example MCP client config:
 }
 ```
 
-### Option B: local repo run
+---
+
+## Configure Your Agent
 
-```json
-{
-  "mcpServers": {
-    "memhub": {
-      "command": "node",
-      "args": ["dist/src/server/mcp-server.js"]
-    }
-  }
-}
+Add the following to your coding agent's system prompt to enable persistent memory:
+
+```markdown
+## Memory System
+
+You have access to persistent memory across conversations. Use it wisely:
+
+- **Remember preferences** — Learn what the user likes and avoid repeating mistakes
+- **Recall decisions** — Build on past reasoning instead of starting from scratch
+- **Store context** — Project knowledge that survives session boundaries
+
+### When to Use
+
+#### `memory_load`
+
+Call when you need context from past conversations:
+- User references something from before
+- You're unsure about user preferences
+- A decision needs historical context
+
+Don't call for simple, self-contained tasks.
+
+#### `memory_update`
+
+Call when you discover something worth remembering:
+- User expresses a preference
+- You made a significant decision with reasoning
+- Project context changed
+
+Don't call for temporary or one-time information.
+
+### Principle
+
+Memory should feel natural — triggered by context, not by schedule. When in doubt, ask: "Would future me benefit from knowing this?"
 ```
 
 ---
 
+## MCP Tools
+
+- `memory_load`  
+  First-turn tool. Load STM context for the current task/session.
+- `memory_update`  
+  Final-turn tool. Write back decisions, preferences, knowledge, and task-state updates.
+
+See [docs/mcp-tools.md](docs/mcp-tools.md) for detailed API reference.
+
+---
+
+## Why MemHub
+
+Most AI memory tools rely on external APIs or simple keyword matching. MemHub is different:
+
+### Semantic Search with Local AI
+
+- **Vector Database**: Powered by LanceDB for fast similarity search
+- **Local Embeddings**: Quantized Transformers.js model runs entirely on your machine
+- **Zero API Costs**: No external services, no API keys, no rate limits
+- **Privacy First**: Your memories never leave your computer
+
+### Git-Native Storage
+
+- **Plain Text**: All memories are Markdown files with YAML front matter
+- **Version Control**: Commit, branch, review, and revert like any code
+- **Human Readable**: Browse and edit memories with any text editor
+- **Team Friendly**: Share memories via git repository
+
+### How It Works
+
+```
+User Query → Local Embedding Model → Vector Search → Ranked Results
+                    ↑                         ↓
+              Runs on CPU              LanceDB Index
+            (no GPU required)         (embedded database)
+```
+
+When you call `memory_load`, MemHub:
+1. Converts your query to a vector using a local quantized model
+2. Searches the LanceDB index for semantically similar memories
+3. Returns ranked results with relevance scores
+
+This means "testing framework preference" finds memories about "Vitest vs Jest decision" — even without exact keyword matches.
+
+---
+
+## Features
+
+- **Semantic Search** — Vector-based similarity search with LanceDB
+- **Local Embeddings** — Quantized Transformers.js model, runs on CPU
+- **Markdown Storage** — Human-readable `.md` files with YAML front matter
+- **Git-Friendly** — Version control, diff, review your memories
+- **MCP Protocol** — Works with Claude Code, Cursor, Cline, Windsurf, and more
+- **One-Line Setup** — `npx -y @synth-coder/memhub init`
+
+---
+
 ## Environment Variables
 
-- `MEMHUB_STORAGE_PATH` (default: `./memories`)
+- `MEMHUB_STORAGE_PATH` (default: `~/.memhub`)
 - `MEMHUB_LOG_LEVEL` (default: `info`, options: `debug|info|warn|error`)
 
 ---
@@ -129,28 +213,24 @@ YYYY-MM-DD-title-slug.md
 
 ---
 
-## MCP Tools
-
-- `memory_load`  
-  First-turn tool. Load STM context for the current task/session.
-- `memory_update`  
-  Final-turn tool. Write back decisions, preferences, knowledge, and task-state updates.
-
-Calling policy: see `docs/tool-calling-policy.md`.
+## Development
 
----
+### Install & Build
 
-## Development
+```bash
+npx pnpm install
+npx pnpm run build
+```
 
 ### Scripts
 
 ```bash
-npm run build
-npm run lint
-npm run typecheck
-npm run test
-npm run test:coverage
-npm run quality
+npx pnpm run build
+npx pnpm run lint
+npx pnpm run format
+npx pnpm run typecheck
+npx pnpm run test
+npx pnpm run quality
 ```
 
 ### Engineering Workflow
@@ -184,9 +264,10 @@ memhub/
 - [x] Architecture and contracts
 - [x] Core storage/service/server implementation
 - [x] Quality gate (lint/typecheck/test/coverage)
+- [x] CLI init command for quick setup
 - [ ] Integration tests
 - [ ] Performance improvements
-- [x] npm release (`@synth-coder/memhub@0.1.3`)
+- [x] npm release (`@synth-coder/memhub@0.2.3`)
 
 ---