@synth-coder/memhub 0.2.3 → 0.2.4

package/.iflow/skills/openspec-propose/SKILL.md

@@ -1,110 +1,110 @@
----
-name: openspec-propose
-description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
-license: MIT
-compatibility: Requires openspec CLI.
-metadata:
-  author: openspec
-  version: "1.0"
-  generatedBy: "1.2.0"
----
-
-Propose a new change - create the change and generate all artifacts in one step.
-
-I'll create a change with artifacts:
-- proposal.md (what & why)
-- design.md (how)
-- tasks.md (implementation steps)
-
-When ready to implement, run /opsx:apply
-
----
-
-**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
-
-**Steps**
-
-1. **If no clear input provided, ask what they want to build**
-
-   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
-   > "What change do you want to work on? Describe what you want to build or fix."
-
-   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
-
-   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
-
-2. **Create the change directory**
-   ```bash
-   openspec new change "<name>"
-   ```
-   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
-
-3. **Get the artifact build order**
-   ```bash
-   openspec status --change "<name>" --json
-   ```
-   Parse the JSON to get:
-   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
-   - `artifacts`: list of all artifacts with their status and dependencies
-
-4. **Create artifacts in sequence until apply-ready**
-
-   Use the **TodoWrite tool** to track progress through the artifacts.
-
-   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
-
-   a. **For each artifact that is `ready` (dependencies satisfied)**:
-      - Get instructions:
-        ```bash
-        openspec instructions <artifact-id> --change "<name>" --json
-        ```
-      - The instructions JSON includes:
-        - `context`: Project background (constraints for you - do NOT include in output)
-        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
-        - `template`: The structure to use for your output file
-        - `instruction`: Schema-specific guidance for this artifact type
-        - `outputPath`: Where to write the artifact
-        - `dependencies`: Completed artifacts to read for context
-      - Read any completed dependency files for context
-      - Create the artifact file using `template` as the structure
-      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
-      - Show brief progress: "Created <artifact-id>"
-
-   b. **Continue until all `applyRequires` artifacts are complete**
-      - After creating each artifact, re-run `openspec status --change "<name>" --json`
-      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
-      - Stop when all `applyRequires` artifacts are done
-
-   c. **If an artifact requires user input** (unclear context):
-      - Use **AskUserQuestion tool** to clarify
-      - Then continue with creation
-
-5. **Show final status**
-   ```bash
-   openspec status --change "<name>"
-   ```
-
-**Output**
-
-After completing all artifacts, summarize:
-- Change name and location
-- List of artifacts created with brief descriptions
-- What's ready: "All artifacts created! Ready for implementation."
-- Prompt: "Run `/opsx:apply` or ask me to implement to start working on the tasks."
-
-**Artifact Creation Guidelines**
-
-- Follow the `instruction` field from `openspec instructions` for each artifact type
-- The schema defines what each artifact should contain - follow it
-- Read dependency artifacts for context before creating new ones
-- Use `template` as the structure for your output file - fill in its sections
-- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
-  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
-  - These guide what you write, but should never appear in the output
-
-**Guardrails**
-- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
-- Always read dependency artifacts before creating a new one
-- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
-- If a change with that name already exists, ask if user wants to continue it or create a new one
-- Verify each artifact file exists after writing before proceeding to next
+---
+name: openspec-propose
+description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx:apply
+
+---
+
+**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
+
+**Steps**
+
+1. **If no clear input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` or ask me to implement to start working on the tasks."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next

package/.prettierrc

@@ -1,11 +1,11 @@
-{
-  "semi": true,
-  "trailingComma": "es5",
-  "singleQuote": true,
-  "printWidth": 100,
-  "tabWidth": 2,
-  "useTabs": false,
-  "bracketSpacing": true,
-  "arrowParens": "avoid",
-  "endOfLine": "lf"
-}
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "bracketSpacing": true,
+  "arrowParens": "avoid",
+  "endOfLine": "lf"
+}

package/AGENTS.md

@@ -1,169 +1,167 @@
-# 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
-# Install dependencies
-pnpm install
-
-# Build
-pnpm run build
-
-# Quality gate (lint + typecheck + test + coverage)
-pnpm run quality
-```
-
-## 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 |
-
-## Project Structure
-
-```
-src/
-  contracts/    # Type definitions, Zod schemas, MCP contracts
-  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 Conventions
-
-### TypeScript Style
-- 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`
-
-### 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
-// 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()),
-});
-```
-
-## 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
-
-## Documentation Guidelines
-
-文档是代码契约的一部分，必须与实现保持同步。
-
-### 何时更新文档
-
-**必须更新文档的场景：**
-
-1. **接口变更** — 新增、修改、删除 MCP 工具参数或返回值
-2. **类型定义变更** — 修改 `src/contracts/types.ts` 中的类型
-3. **Schema 变更** — 修改 `src/contracts/schemas.ts` 中的 Zod schema
-4. **行为变更** — 工具的调用逻辑、错误处理、默认值发生变化
-5. **版本发布** — package.json 版本号变更时，同步更新 README 中的版本引用
-
-**文档与代码的对应关系：**
-
-| 代码文件 | 对应文档 |
-|---------|---------|
-| `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) |
-
-### 文档更新流程
-
-1. 修改代码后，检查相关文档是否需要同步
-2. 对照代码实现校对文档描述
-3. 移除文档中不存在于代码的参数/字段
-4. 补充文档中缺失的新增参数/字段
-5. 确保示例代码与实际类型定义一致
-
-### 验证方法
-
-```bash
-# 对比代码中的类型定义与文档描述
-grep -A 20 "interface MemoryLoadInput" src/contracts/types.ts
-grep -A 20 "MemoryLoadInput" docs/contracts.md
-```
-
-## Git Workflow
-
-- Commit message format: `type: description` (feat/fix/docs/chore/refactor/test)
-- Always run quality gate before committing
-- PR title format: `[scope] Description`
-
-## Dos and Don'ts
-
-### Do
-- Run `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
-
-### 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)
-
-## 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.
+# 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)