@synth-coder/memhub 0.2.3 → 0.2.5

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,70 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+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

@@ -6,38 +6,36 @@ MemHub is a Git-friendly memory MCP server for coding agents. It stores decision
 
 **Tech Stack**: TypeScript (ES2022), Node.js 18+, MCP SDK, Zod, LanceDB, Transformers.js
 
+---
+
 ## Dev Environment
 
 ```bash
-# Install dependencies
-pnpm install
-
-# Build
-pnpm run build
-
-# Quality gate (lint + typecheck + test + coverage)
-pnpm run quality
+npx pnpm install        # Install dependencies
+npx pnpm run build      # Compile TypeScript
+npx pnpm run quality    # Quality gate (lint + typecheck + test + coverage)
 ```
 
-## Key Commands
-
 | Command | Description |
 |---------|-------------|
-| `pnpm run build` | Compile TypeScript |
-| `pnpm run lint` | ESLint check |
-| `pnpm run lint:fix` | Auto-fix lint issues |
-| `pnpm run typecheck` | TypeScript type check |
-| `pnpm run test` | Run Vitest tests |
-| `pnpm run test:watch` | Watch mode tests |
-| `pnpm run test:coverage` | Tests with coverage |
-| `pnpm run quality` | Full quality gate |
-| `pnpm vitest run -t "test name"` | Run specific test |
+| `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)
@@ -46,9 +44,11 @@ test/           # Vitest unit tests mirroring src/ structure
 docs/           # Documentation
 ```
 
-## Coding Conventions
+---
+
+## Coding Style
 
-### TypeScript 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
@@ -60,11 +60,6 @@ docs/           # Documentation
 - `kebab-case.ts` for all files
 - Test files: `<module>.test.ts` or `<module>-edge.test.ts`
 
-### Code Organization
-- Contracts first: define types and schemas before implementation
-- TDD workflow: red → green → refactor
-- One export per file preferred; barrel exports in `index.ts`
-
 ### Example Code Style
 
 ```typescript
@@ -90,67 +85,79 @@ export const MemorySchema = z.object({
 });
 ```
 
-## Testing Guidelines
+---
 
-- Test 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 `pnpm run quality` before committing
+## Workflows
 
-## Documentation Guidelines
+### 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`
 
-1. **接口变更** — 新增、修改、删除 MCP 工具参数或返回值
-2. **类型定义变更** — 修改 `src/contracts/types.ts` 中的类型
-3. **Schema 变更** — 修改 `src/contracts/schemas.ts` 中的 Zod schema
-4. **行为变更** — 工具的调用逻辑、错误处理、默认值发生变化
-5. **版本发布** — package.json 版本号变更时，同步更新 README 中的版本引用
+### 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`
 
-| 代码文件 | 对应文档 |
-|---------|---------|
-| `src/contracts/types.ts` | `docs/contracts.md`、`docs/architecture.md` |
-| `src/contracts/schemas.ts` | `docs/contracts.md` |
-| `src/contracts/mcp.ts` | `docs/contracts.md`、`docs/tool-calling-policy.md` |
-| `package.json` (version) | `README.md` (Roadmap) |
+---
 
-### 文档更新流程
+## Documentation Sync
 
-1. 修改代码后，检查相关文档是否需要同步
-2. 对照代码实现校对文档描述
-3. 移除文档中不存在于代码的参数/字段
-4. 补充文档中缺失的新增参数/字段
-5. 确保示例代码与实际类型定义一致
+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 |
 
-```bash
-# 对比代码中的类型定义与文档描述
-grep -A 20 "interface MemoryLoadInput" src/contracts/types.ts
-grep -A 20 "MemoryLoadInput" docs/contracts.md
-```
+---
+
+## 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 format: `type: description` (feat/fix/docs/chore/refactor/test)
+- Commit message: `type: description` (feat/fix/docs/chore/refactor/test)
 - Always run quality gate before committing
-- PR title format: `[scope] Description`
+- PR title: `[scope] Description`
+
+---
 
 ## Dos and Don'ts
 
 ### Do
-- Run `pnpm run quality` before committing
+- 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 and schemas together
+- Update types, schemas, and docs together
 
 ### Don't
 - Skip the quality gate
@@ -158,12 +165,3 @@ grep -A 20 "MemoryLoadInput" docs/contracts.md
 - Mutate function parameters
 - Add code without corresponding tests
 - Commit directly to main (use branches for features)
-
-## MCP Tool Reference
-
-MemHub exposes two primary tools:
-
-1. **memory_load** - First-turn tool to load STM context
-2. **memory_update** - Final-turn tool to write back decisions/knowledge
-
-See `docs/tool-calling-policy.md` for detailed usage patterns.