@synth-coder/memhub 0.2.4 → 0.2.5

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,167 +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
-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)
+# 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

@@ -11,7 +11,7 @@ Git-friendly memory MCP server for coding agents.
 Configure MemHub for your AI agent with a single command:
 
 ```bash
-npx -y @synth-coder/memhub init
+npx -y @synth-coder/memhub@latest init
 ```
 
 This launches an interactive prompt to select your agent. MemHub will:
@@ -34,16 +34,16 @@ This launches an interactive prompt to select your agent. MemHub will:
 
 ```bash
 # Interactive selection (global - default)
-npx -y @synth-coder/memhub init
+npx -y @synth-coder/memhub@latest init
 
 # Skip interactive prompt
-npx -y @synth-coder/memhub init -a claude-code
+npx -y @synth-coder/memhub@latest init -a claude-code
 
 # Configure for current project only (local)
-npx -y @synth-coder/memhub init -a cursor -l
+npx -y @synth-coder/memhub@latest init -a cursor -l
 
 # Update existing configuration
-npx -y @synth-coder/memhub init -a claude-code --force
+npx -y @synth-coder/memhub@latest init -a claude-code --force
 ```
 
 | Option | Description |
@@ -55,7 +55,7 @@ npx -y @synth-coder/memhub init -a claude-code --force
 ### Run as MCP Server
 
 ```bash
-npx -y @synth-coder/memhub
+npx -y @synth-coder/memhub@latest
 ```
 
 > On Windows, do **not** append `memhub` after the package name.
@@ -69,7 +69,7 @@ If you prefer manual setup, add this to your MCP client config:
   "mcpServers": {
     "memhub": {
       "command": "npx",
-      "args": ["-y", "@synth-coder/memhub"],
+      "args": ["-y", "@synth-coder/memhub@latest"],
       "env": {
         "MEMHUB_STORAGE_PATH": "/absolute/path/to/memories",
         "MEMHUB_LOG_LEVEL": "info"
@@ -79,6 +79,14 @@ If you prefer manual setup, add this to your MCP client config:
 }
 ```
 
+For Codex (`~/.codex/config.toml`), use TOML key `mcp_servers`:
+
+```toml
+[mcp_servers.memhub]
+command = "npx"
+args = ["-y", "@synth-coder/memhub@latest"]
+```
+
 ---
 
 ## Configure Your Agent
@@ -175,7 +183,7 @@ This means "testing framework preference" finds memories about "Vitest vs Jest d
 - **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`
+- **One-Line Setup** — `npx -y @synth-coder/memhub@latest init`
 
 ---
 
@@ -267,7 +275,7 @@ memhub/
 - [x] CLI init command for quick setup
 - [ ] Integration tests
 - [ ] Performance improvements
-- [x] npm release (`@synth-coder/memhub@0.2.3`)
+- [x] npm release (`@synth-coder/memhub@0.2.5`)
 
 ---