@synth-coder/memhub 0.2.2 → 0.2.3

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,26 +1,169 @@
-你是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
+# 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.